@ozura/elements 1.2.1 → 1.2.3

package/dist/oz-elements.umd.js

@@ -204,7 +204,7 @@
         if (msg.includes('timeout') || msg.includes('timed out')) {
             return 'The request timed out. Please try again.';
         }
-        if (msg.includes('http 5') || msg.includes('500') || msg.includes('502') || msg.includes('503')) {
+        if (msg.includes('http 5') || /\b5\d{2}\b/.test(msg)) {
             return 'A server error occurred. Please try again shortly.';
         }
         return null;
@@ -224,7 +224,7 @@
         if (msg.includes('cvv') || msg.includes('cvc') || msg.includes('security code')) {
             return 'The CVV code is invalid. Please check and try again.';
         }
-        if (msg.includes('insufficient') || msg.includes('funds')) {
+        if (msg.includes('insufficient funds')) {
             return 'Your card has insufficient funds. Please use a different card.';
         }
         if (msg.includes('declined') || msg.includes('do not honor')) {
@@ -382,7 +382,7 @@
      * it never holds raw card data — all sensitive values live in the iframe.
      */
     class OzElement {
-        constructor(elementType, options, vaultId, frameBaseUrl, fonts = [], appearanceStyle) {
+        constructor(elementType, options, vaultId, frameBaseUrl, fonts = [], appearanceStyle, onDestroy, debug = false) {
             this.iframe = null;
             this._frameWindow = null;
             this._ready = false;
@@ -390,6 +390,7 @@
             this._loadTimer = null;
             this.pendingMessages = [];
             this.handlers = new Map();
+            this.debug = false;
             this.elementType = elementType;
             this.options = sanitizeOptions(options);
             this.vaultId = vaultId;
@@ -398,6 +399,8 @@
             this.fonts = fonts;
             this.appearanceStyle = appearanceStyle;
             this.frameId = `oz-${elementType}-${uuid()}`;
+            this._onDestroy = onDestroy;
+            this.debug = debug;
         }
         /** The element type this proxy represents. */
         get type() {
@@ -437,11 +440,17 @@
             accountNumber: 'account number',
             routingNumber: 'routing number',
         }[this.elementType]) !== null && _a !== void 0 ? _a : this.elementType} input`;
-            // Note: the `sandbox` attribute is intentionally NOT set. Field values are
-            // delivered to the tokenizer iframe via a MessageChannel port (transferred
-            // in OZ_BEGIN_COLLECT), so no window.parent named-frame lookup is needed.
-            // The security boundary is the vault URL hardcoded at build time and the
-            // origin checks on every postMessage, not the sandbox flag.
+            // sandbox="allow-scripts" gives correct iframe isolation:
+            // - Scripts run (allow-scripts), so the field JS executes normally.
+            // - NO allow-same-origin: the frame cannot access window.parent's DOM,
+            //   localStorage, or cookies — prevents sandbox escape even if served
+            //   from the same origin.
+            // - NO allow-top-navigation: a rogue/compromised element frame cannot
+            //   navigate window.top (clickjacking prevention).
+            // - NO allow-forms / allow-popups: reduces attack surface.
+            // Field values are delivered via postMessage, so no parent access is
+            // needed — allow-scripts alone is sufficient.
+            iframe.setAttribute('sandbox', 'allow-scripts');
             // Use hash instead of query string — survives clean-URL redirects from static servers.
             // parentOrigin lets the frame target postMessage to the merchant origin instead of '*'.
             const parentOrigin = typeof window !== 'undefined' ? window.location.origin : '';
@@ -553,9 +562,14 @@
          * and prevents future use. Distinct from `unmount()` which allows re-mounting.
          */
         destroy() {
+            var _a;
             this.unmount();
             this.handlers.clear();
             this._destroyed = true;
+            // Notify OzVault so it can prune the stale frameId entry from its elements
+            // and completionState maps. Without this, manually calling el.destroy() leaks
+            // map entries that grow unboundedly in SPA scenarios with repeated mount/unmount.
+            (_a = this._onDestroy) === null || _a === void 0 ? void 0 : _a.call(this);
         }
         // ─── Called by OzVault ───────────────────────────────────────────────────
         /**
@@ -592,7 +606,7 @@
                     }
                     this._frameWindow = (_b = (_a = this.iframe) === null || _a === void 0 ? void 0 : _a.contentWindow) !== null && _b !== void 0 ? _b : null;
                     const mergedOptions = Object.assign(Object.assign({}, this.options), { style: mergeAppearanceWithElementStyle(this.appearanceStyle, this.options.style) });
-                    this.post(Object.assign({ type: 'OZ_INIT', elementType: this.elementType, options: sanitizeOptions(mergedOptions), frameId: this.frameId }, (this.fonts.length > 0 ? { fonts: this.fonts } : {})));
+                    this.post(Object.assign({ type: 'OZ_INIT', elementType: this.elementType, options: sanitizeOptions(mergedOptions), frameId: this.frameId, debug: this.debug }, (this.fonts.length > 0 ? { fonts: this.fonts } : {})));
                     this.pendingMessages.forEach(m => this.send(m));
                     this.pendingMessages = [];
                     this.emit('ready', undefined);
@@ -706,13 +720,14 @@
     // ─── Phone ───────────────────────────────────────────────────────────────────
     /**
      * Validates E.164 phone format: starts with +, 1–3 digit country code,
-     * followed by 7–12 digits, total ≤50 characters.
+     * followed by 7–12 digits, max 15 digits total (E.164 spec cap = 16 chars
+     * including the leading +).
      *
      * Matches the output of checkout's formatPhoneForAPI() function.
      * Examples: "+15551234567", "+447911123456", "+61412345678"
      */
     function validateE164Phone(phone) {
-        return /^\+[1-9]\d{6,49}$/.test(phone) && phone.length <= 50;
+        return /^\+[1-9]\d{6,14}$/.test(phone);
     }
     // ─── Field length ─────────────────────────────────────────────────────────────
     /** Returns true when the string is non-empty and ≤50 characters (cardSale schema). */
@@ -915,12 +930,12 @@
      *
      * @example
      * // Simplest — just pass sessionUrl, no need to call this directly
-     * const vault = await OzVault.create({ pubKey: 'pk_live_...', sessionUrl: '/api/oz-session' });
+     * const vault = await OzVault.create({ pubKey: 'pk_prod_...', sessionUrl: '/api/oz-session' });
      *
      * @example
      * // Manual — use when you need custom headers
      * const vault = await OzVault.create({
-     *   pubKey: 'pk_live_...',
+     *   pubKey: 'pk_prod_...',
      *   getSessionKey: createSessionFetcher('/api/oz-session'),
      * });
      */
@@ -958,7 +973,22 @@
                     throw new OzError(`Could not reach session endpoint (${url}): ${msg}`, undefined, 'network');
                 }
             }
-            const data = await res.json().catch(() => ({}));
+            // Parse JSON separately from the ok-check so that a non-JSON error body
+            // (HTML error page, WAF block, CDN 503) produces the right error code.
+            // Previously res.json() was attempted before res.ok was checked; a parse
+            // failure on a 5xx HTML body would fall through as {} and produce a
+            // misleading 'validation' code when the real cause is a server/network issue.
+            let data = {};
+            try {
+                data = await res.json();
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new OzError(`Session endpoint returned HTTP ${res.status} with a non-JSON body`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
+                }
+                // HTTP 200 but body isn't JSON — this is a misconfigured session endpoint.
+                throw new OzError('Session endpoint returned HTTP 200 but the response body is not valid JSON. Check your /api/oz-session implementation.', undefined, 'validation');
+            }
             if (!res.ok) {
                 throw new OzError(typeof data.error === 'string' && data.error
                     ? data.error
@@ -976,10 +1006,19 @@
     }
 
     function isCardMetadata(v) {
-        return !!v && typeof v === 'object' && typeof v.last4 === 'string';
+        if (!v || typeof v !== 'object')
+            return false;
+        const r = v;
+        return (typeof r.last4 === 'string' &&
+            typeof r.brand === 'string' &&
+            typeof r.expMonth === 'string' &&
+            typeof r.expYear === 'string');
     }
     function isBankAccountMetadata(v) {
-        return !!v && typeof v === 'object' && typeof v.last4 === 'string';
+        if (!v || typeof v !== 'object')
+            return false;
+        const r = v;
+        return typeof r.last4 === 'string' && typeof r.routingNumberLast4 === 'string';
     }
     const DEFAULT_FRAME_BASE_URL = "https://elements.ozura.com";
     /**
@@ -989,16 +1028,10 @@
      * Use the static `OzVault.create()` factory — do not call `new OzVault()` directly.
      *
      * @example
+     * // Recommended — pass sessionUrl and let the SDK call your backend automatically
      * const vault = await OzVault.create({
-     *   pubKey: 'pk_live_...',
-     *   fetchWaxKey: async (sessionId) => {
-     *     // Call your backend — which calls ozura.mintWaxKey() from @ozura/elements/server
-     *     const { waxKey } = await fetch('/api/mint-wax', {
-     *       method: 'POST',
-     *       body: JSON.stringify({ sessionId }),
-     *     }).then(r => r.json());
-     *     return waxKey;
-     *   },
+     *   pubKey: 'pk_prod_...',  // or 'pk_test_...' for test mode
+     *   sessionUrl: '/api/oz-session',  // backend endpoint that calls ozura.createSession()
      * });
      * const cardNum = vault.createElement('cardNumber');
      * cardNum.mount('#card-number');
@@ -1044,6 +1077,11 @@
             this.tokenizationSessionId = tokenizationSessionId;
             this.pubKey = options.pubKey;
             this.frameBaseUrl = options.frameBaseUrl || DEFAULT_FRAME_BASE_URL;
+            // Validate immediately after assignment
+            if (!this.frameBaseUrl.startsWith('https://') &&
+                !this.frameBaseUrl.startsWith('http://localhost')) {
+                throw new OzError('frameBaseUrl must use HTTPS (http://localhost is allowed for local development)', undefined, 'config');
+            }
             this.frameOrigin = new URL(this.frameBaseUrl).origin;
             this.fonts = (_a = options.fonts) !== null && _a !== void 0 ? _a : [];
             this.resolvedAppearance = resolveAppearance(options.appearance);
@@ -1152,7 +1190,7 @@
             // the OZ_INIT sent at that point had an empty waxKey. Send a follow-up now
             // so the tokenizer has the key stored before any createToken() call.
             if (vault.tokenizerReady) {
-                vault.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey });
+                vault.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey, debug: vault._debug });
             }
             vault.log('wax key received — vault ready');
             return vault;
@@ -1234,7 +1272,12 @@
                 this.completionState.delete(existing.frameId);
                 existing.destroy();
             }
-            const el = new OzElement(type, options, this.vaultId, this.frameBaseUrl, this.fonts, this.resolvedAppearance);
+            const el = new OzElement(type, options, this.vaultId, this.frameBaseUrl, this.fonts, this.resolvedAppearance, () => {
+                // Prune vault-level maps when the element is manually destroyed so they
+                // don't grow unboundedly in SPA scenarios with repeated mount/unmount cycles.
+                this.elements.delete(el.frameId);
+                this.completionState.delete(el.frameId);
+            }, this._debug);
             this.elements.set(el.frameId, el);
             typeMap.set(type, el);
             return el;
@@ -1317,7 +1360,6 @@
                     this.sendToTokenizer({
                         type: 'OZ_BANK_TOKENIZE',
                         requestId,
-                        waxKey: this.waxKey,
                         tokenizationSessionId: this.tokenizationSessionId,
                         pubKey: this.pubKey,
                         firstName: options.firstName.trim(),
@@ -1325,7 +1367,10 @@
                         fieldCount: readyBankElements.length,
                     }, bankChannels.map(ch => ch.port1));
                     this.log('OZ_BANK_TOKENIZE sent', { requestIdPrefix: `${requestId.slice(0, 12)}...`, fieldCount: readyBankElements.length });
-                    readyBankElements.forEach((el, i) => el.beginCollect(requestId, bankChannels[i].port2));
+                    readyBankElements.forEach((el, i) => {
+                        this.log('OZ_BEGIN_COLLECT dispatched', { type: el.type, requestIdPrefix: `${requestId.slice(0, 12)}...` });
+                        el.beginCollect(requestId, bankChannels[i].port2);
+                    });
                     const bankTimeoutId = setTimeout(() => {
                         if (this.bankTokenizeResolvers.has(requestId)) {
                             this.bankTokenizeResolvers.delete(requestId);
@@ -1409,7 +1454,11 @@
             }
             this._tokenizing = 'card';
             const requestId = `req-${uuid()}`;
-            this.log('createToken() called');
+            this.log('createToken() called', {
+                requestIdPrefix: requestId.slice(0, 12),
+                fields: readyElements.map(el => el.type),
+                billingPresent: Boolean(options.billing),
+            });
             return new Promise((resolve, reject) => {
                 // Capture the reset generation so cleanup() only zeros _tokenizing when it
                 // still belongs to this invocation — not a newer one that started after a reset.
@@ -1434,7 +1483,6 @@
                     this.sendToTokenizer({
                         type: 'OZ_TOKENIZE',
                         requestId,
-                        waxKey: this.waxKey,
                         tokenizationSessionId: this.tokenizationSessionId,
                         pubKey: this.pubKey,
                         firstName,
@@ -1447,7 +1495,10 @@
                     if (cardEntry)
                         cardEntry.tokenizeStartMs = tokenizeStartMs;
                     // Tell each ready element frame to send its raw value to the tokenizer
-                    readyElements.forEach((el, i) => el.beginCollect(requestId, cardChannels[i].port2));
+                    readyElements.forEach((el, i) => {
+                        this.log('OZ_BEGIN_COLLECT dispatched', { type: el.type, requestIdPrefix: `${requestId.slice(0, 12)}...` });
+                        el.beginCollect(requestId, cardChannels[i].port2);
+                    });
                     const cardTimeoutId = setTimeout(() => {
                         if (this.tokenizeResolvers.has(requestId)) {
                             this.tokenizeResolvers.delete(requestId);
@@ -1500,6 +1551,7 @@
                 this.tokenizeResolvers.forEach(({ reject, timeoutId }, requestId) => {
                     if (timeoutId != null)
                         clearTimeout(timeoutId);
+                    this.log('OZ_TOKENIZE_CANCEL sent (reset)', { requestIdPrefix: `${requestId.slice(0, 12)}...` });
                     this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
                     reject(new OzError('Vault was reset while tokenization was in progress.'));
                 });
@@ -1507,6 +1559,7 @@
                 this.bankTokenizeResolvers.forEach(({ reject, timeoutId }, requestId) => {
                     if (timeoutId != null)
                         clearTimeout(timeoutId);
+                    this.log('OZ_TOKENIZE_CANCEL sent (reset, bank)', { requestIdPrefix: `${requestId.slice(0, 12)}...` });
                     this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
                     reject(new OzError('Vault was reset while tokenization was in progress.'));
                 });
@@ -1681,7 +1734,7 @@
             }
         }
         handleMessage(event) {
-            var _a;
+            var _a, _b;
             if (this._destroyed)
                 return;
             // Only accept messages from our frame origin (defense in depth; prevents
@@ -1696,6 +1749,15 @@
                 this.handleTokenizerMessage(msg);
                 return;
             }
+            // OZ_TOKEN_ERROR can arrive from element frames when the MessagePort
+            // transferred in OZ_BEGIN_COLLECT was dropped by the browser (e.g. the
+            // frame navigated). These carry a requestId but no frameId — route them
+            // through handleTokenizerMessage so the pending promise is rejected
+            // immediately rather than waiting for the 30 s collect timeout.
+            if (msg.type === 'OZ_TOKEN_ERROR') {
+                this.handleTokenizerMessage(msg);
+                return;
+            }
             // Route to the matching element
             const frameId = msg.frameId;
             if (frameId) {
@@ -1713,6 +1775,23 @@
                         }
                         this.log('element iframe ready', { type: el.type, frameIdPrefix: frameId.slice(0, 8) });
                     }
+                    // Relay debug/warning messages from element iframes into the parent
+                    // DevTools console. Element frames run in cross-origin iframes whose
+                    // console context is invisible to developers without a frame selector switch.
+                    // Errors are always surfaced (genuine failures). Warnings are only emitted
+                    // when debug mode is on — CSS var() and font-host warnings fire on every
+                    // style update and would pollute production consoles otherwise.
+                    if (msg.type === 'OZ_DEBUG_LOG') {
+                        const level = typeof msg.level === 'string' ? msg.level : 'warn';
+                        const message = typeof msg.message === 'string' ? msg.message : String((_b = msg.message) !== null && _b !== void 0 ? _b : '');
+                        if (level === 'error') {
+                            console.error(`[OzVault:${el.type}] ${message}`);
+                        }
+                        else if (this._debug) {
+                            console.warn(`[OzVault:${el.type}] ${message}`);
+                        }
+                        return;
+                    }
                     // Intercept OZ_CHANGE before forwarding — handle auto-advance and CVV sync
                     if (msg.type === 'OZ_CHANGE') {
                         this.handleElementChange(msg, el);
@@ -1757,7 +1836,7 @@
             }
         }
         handleTokenizerMessage(msg) {
-            var _a, _b, _c, _d;
+            var _a, _b, _c, _d, _e;
             switch (msg.type) {
                 case 'OZ_FRAME_READY':
                     if (msg.__ozVersion !== PROTOCOL_VERSION) {
@@ -1775,9 +1854,10 @@
                     // Deliver the wax key via OZ_INIT so the tokenizer stores it internally.
                     // If waxKey is still empty (fetchWaxKey hasn't resolved yet), it will be
                     // sent again from create() once the key is available.
-                    this.sendToTokenizer(Object.assign({ type: 'OZ_INIT', frameId: '__tokenizer__' }, (this.waxKey ? { waxKey: this.waxKey } : {})));
+                    this.sendToTokenizer(Object.assign(Object.assign({ type: 'OZ_INIT', frameId: '__tokenizer__' }, (this.waxKey ? { waxKey: this.waxKey } : {})), { debug: this._debug }));
                     (_c = this._onReady) === null || _c === void 0 ? void 0 : _c.call(this);
                     this.log('tokenizer iframe ready', { protocolVersion: (_d = msg.__ozVersion) !== null && _d !== void 0 ? _d : null });
+                    this.log('vault state', this.debugState());
                     break;
                 case 'OZ_TOKEN_RESULT': {
                     if (typeof msg.requestId !== 'string' || !msg.requestId) {
@@ -1803,6 +1883,7 @@
                         pending.resolve(Object.assign(Object.assign({ token,
                             cvcSession }, (card ? { card } : {})), (pending.billing ? { billing: pending.billing } : {})));
                         this.log('token received', {
+                            requestIdPrefix: msg.requestId.slice(0, 12),
                             elapsedMs: pending.tokenizeStartMs != null ? Date.now() - pending.tokenizeStartMs : null,
                             tokenPresent: true,
                             cvcSessionPresent: true,
@@ -1834,7 +1915,7 @@
                         if (pending.timeoutId != null)
                             clearTimeout(pending.timeoutId);
                         const willRefresh = this.isRefreshableAuthError(errorCode, raw) && !pending.retried && Boolean(this._storedFetchWaxKey);
-                        this.log('token error', { errorCode, willRefresh });
+                        this.log('token error', { requestIdPrefix: msg.requestId.slice(0, 12), errorCode, willRefresh });
                         // Auto-refresh: if the wax key expired or was consumed and we haven't
                         // already retried for this request, transparently re-mint and retry.
                         if (willRefresh) {
@@ -1852,6 +1933,17 @@
                                     pending.reject(new OzError('Vault was reset while tokenization was in progress.'));
                                     return;
                                 }
+                                // Verify all elements from the original call are still mounted and
+                                // ready. If any were destroyed (e.g. the merchant called
+                                // createElement() or destroy() during the async refresh), the
+                                // beginCollect() calls below would silently no-op — the tokenizer
+                                // would wait forever for field values that never arrive. Reject
+                                // immediately with a clear message instead of hanging 30 seconds.
+                                const allCardElementsStillReady = pending.readyElements.every(el => this.elements.has(el.frameId) && el.isReady);
+                                if (!allCardElementsStillReady) {
+                                    pending.reject(new OzError('Card fields changed during session refresh. Please re-enter your card details.'));
+                                    return;
+                                }
                                 const newRequestId = `req-${uuid()}`;
                                 // _tokenizing is still 'card' (cleanup() hasn't been called yet)
                                 this.tokenizeResolvers.set(newRequestId, Object.assign(Object.assign({}, pending), { retried: true }));
@@ -1860,14 +1952,16 @@
                                     this.sendToTokenizer({
                                         type: 'OZ_TOKENIZE',
                                         requestId: newRequestId,
-                                        waxKey: this.waxKey,
                                         tokenizationSessionId: this.tokenizationSessionId,
                                         pubKey: this.pubKey,
                                         firstName: pending.firstName,
                                         lastName: pending.lastName,
                                         fieldCount: pending.fieldCount,
                                     }, retryCardChannels.map(ch => ch.port1));
-                                    pending.readyElements.forEach((el, i) => el.beginCollect(newRequestId, retryCardChannels[i].port2));
+                                    pending.readyElements.forEach((el, i) => {
+                                        this.log('OZ_BEGIN_COLLECT dispatched (retry)', { type: el.type, requestIdPrefix: `${newRequestId.slice(0, 12)}...` });
+                                        el.beginCollect(newRequestId, retryCardChannels[i].port2);
+                                    });
                                     const retryCardTimeoutId = setTimeout(() => {
                                         if (this.tokenizeResolvers.has(newRequestId)) {
                                             this.tokenizeResolvers.delete(newRequestId);
@@ -1884,68 +1978,80 @@
                                     pending.reject(setupErr instanceof OzError ? setupErr : new OzError('Retry tokenization failed to start'));
                                 }
                             }).catch((refreshErr) => {
-                                const msg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
-                                pending.reject(new OzError(msg, undefined, 'auth'));
+                                const errMsg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
+                                pending.reject(new OzError(errMsg, undefined, 'auth'));
                             });
                             break;
                         }
                         pending.reject(new OzError(normalizeVaultError(raw), raw, errorCode));
                     }
-                    // Also check bank resolvers — both card and bank errors use OZ_TOKEN_ERROR
-                    const bankPending = this.bankTokenizeResolvers.get(msg.requestId);
-                    if (bankPending) {
-                        this.bankTokenizeResolvers.delete(msg.requestId);
-                        if (bankPending.timeoutId != null)
-                            clearTimeout(bankPending.timeoutId);
-                        if (this.isRefreshableAuthError(errorCode, raw) && !bankPending.retried && this._storedFetchWaxKey) {
-                            const resetCountAtRetry = this._resetCount;
-                            this.refreshWaxKey().then(() => {
-                                if (this._destroyed) {
-                                    bankPending.reject(new OzError('Vault destroyed during wax key refresh.'));
-                                    return;
-                                }
-                                if (this._resetCount !== resetCountAtRetry) {
-                                    bankPending.reject(new OzError('Vault was reset while tokenization was in progress.'));
-                                    return;
-                                }
-                                const newRequestId = `req-${uuid()}`;
-                                this.bankTokenizeResolvers.set(newRequestId, Object.assign(Object.assign({}, bankPending), { retried: true }));
-                                try {
-                                    const retryBankChannels = bankPending.readyElements.map(() => new MessageChannel());
-                                    this.sendToTokenizer({
-                                        type: 'OZ_BANK_TOKENIZE',
-                                        requestId: newRequestId,
-                                        waxKey: this.waxKey,
-                                        tokenizationSessionId: this.tokenizationSessionId,
-                                        pubKey: this.pubKey,
-                                        firstName: bankPending.firstName,
-                                        lastName: bankPending.lastName,
-                                        fieldCount: bankPending.fieldCount,
-                                    }, retryBankChannels.map(ch => ch.port1));
-                                    bankPending.readyElements.forEach((el, i) => el.beginCollect(newRequestId, retryBankChannels[i].port2));
-                                    const retryBankTimeoutId = setTimeout(() => {
-                                        if (this.bankTokenizeResolvers.has(newRequestId)) {
-                                            this.bankTokenizeResolvers.delete(newRequestId);
-                                            this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId: newRequestId });
-                                            bankPending.reject(new OzError('Bank tokenization timed out after wax key refresh.', undefined, 'timeout'));
-                                        }
-                                    }, 30000);
-                                    const retryBankEntry = this.bankTokenizeResolvers.get(newRequestId);
-                                    if (retryBankEntry)
-                                        retryBankEntry.timeoutId = retryBankTimeoutId;
-                                }
-                                catch (setupErr) {
-                                    this.bankTokenizeResolvers.delete(newRequestId);
-                                    bankPending.reject(setupErr instanceof OzError ? setupErr : new OzError('Retry bank tokenization failed to start'));
-                                }
-                            }).catch((refreshErr) => {
-                                const msg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
-                                bankPending.reject(new OzError(msg, undefined, 'auth'));
-                            });
-                            break;
+                    else {
+                        // Also check bank resolvers — both card and bank errors use OZ_TOKEN_ERROR.
+                        // Use else-if rather than sequential checks so a UUID collision (however
+                        // improbable) can never trigger double-rejection of two unrelated resolvers.
+                        const bankPending = this.bankTokenizeResolvers.get(msg.requestId);
+                        if (bankPending) {
+                            this.bankTokenizeResolvers.delete(msg.requestId);
+                            if (bankPending.timeoutId != null)
+                                clearTimeout(bankPending.timeoutId);
+                            if (this.isRefreshableAuthError(errorCode, raw) && !bankPending.retried && this._storedFetchWaxKey) {
+                                const resetCountAtRetry = this._resetCount;
+                                this.refreshWaxKey().then(() => {
+                                    if (this._destroyed) {
+                                        bankPending.reject(new OzError('Vault destroyed during wax key refresh.'));
+                                        return;
+                                    }
+                                    if (this._resetCount !== resetCountAtRetry) {
+                                        bankPending.reject(new OzError('Vault was reset while tokenization was in progress.'));
+                                        return;
+                                    }
+                                    // Same stale-element guard as the card retry path above.
+                                    const allBankElementsStillReady = bankPending.readyElements.every(el => this.elements.has(el.frameId) && el.isReady);
+                                    if (!allBankElementsStillReady) {
+                                        bankPending.reject(new OzError('Bank fields changed during session refresh. Please re-enter your account details.'));
+                                        return;
+                                    }
+                                    const newRequestId = `req-${uuid()}`;
+                                    this.bankTokenizeResolvers.set(newRequestId, Object.assign(Object.assign({}, bankPending), { retried: true }));
+                                    try {
+                                        const retryBankChannels = bankPending.readyElements.map(() => new MessageChannel());
+                                        this.sendToTokenizer({
+                                            type: 'OZ_BANK_TOKENIZE',
+                                            requestId: newRequestId,
+                                            tokenizationSessionId: this.tokenizationSessionId,
+                                            pubKey: this.pubKey,
+                                            firstName: bankPending.firstName,
+                                            lastName: bankPending.lastName,
+                                            fieldCount: bankPending.fieldCount,
+                                        }, retryBankChannels.map(ch => ch.port1));
+                                        bankPending.readyElements.forEach((el, i) => {
+                                            this.log('OZ_BEGIN_COLLECT dispatched (retry)', { type: el.type, requestIdPrefix: `${newRequestId.slice(0, 12)}...` });
+                                            el.beginCollect(newRequestId, retryBankChannels[i].port2);
+                                        });
+                                        const retryBankTimeoutId = setTimeout(() => {
+                                            if (this.bankTokenizeResolvers.has(newRequestId)) {
+                                                this.bankTokenizeResolvers.delete(newRequestId);
+                                                this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId: newRequestId });
+                                                bankPending.reject(new OzError('Bank tokenization timed out after wax key refresh.', undefined, 'timeout'));
+                                            }
+                                        }, 30000);
+                                        const retryBankEntry = this.bankTokenizeResolvers.get(newRequestId);
+                                        if (retryBankEntry)
+                                            retryBankEntry.timeoutId = retryBankTimeoutId;
+                                    }
+                                    catch (setupErr) {
+                                        this.bankTokenizeResolvers.delete(newRequestId);
+                                        bankPending.reject(setupErr instanceof OzError ? setupErr : new OzError('Retry bank tokenization failed to start'));
+                                    }
+                                }).catch((refreshErr) => {
+                                    const errMsg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
+                                    bankPending.reject(new OzError(errMsg, undefined, 'auth'));
+                                });
+                                break;
+                            }
+                            bankPending.reject(new OzError(normalizeBankVaultError(raw), raw, errorCode));
                         }
-                        bankPending.reject(new OzError(normalizeBankVaultError(raw), raw, errorCode));
-                    }
+                    } // end else (bank path)
                     break;
                 }
                 case 'OZ_BANK_TOKEN_RESULT': {
@@ -1981,6 +2087,23 @@
                     }
                     break;
                 }
+                case 'OZ_DEBUG_LOG': {
+                    // Relay warnings/errors from the tokenizer iframe into the parent page's
+                    // DevTools console. The tokenizer runs in a cross-origin iframe whose
+                    // console context is invisible to most developers unless they manually
+                    // switch the DevTools frame selector.
+                    // Errors are always surfaced; warnings only in debug mode to avoid
+                    // polluting production consoles.
+                    const level = typeof msg.level === 'string' ? msg.level : 'warn';
+                    const message = typeof msg.message === 'string' ? msg.message : String((_e = msg.message) !== null && _e !== void 0 ? _e : '');
+                    if (level === 'error') {
+                        console.error(`[OzVault:tokenizer] ${message}`);
+                    }
+                    else if (this._debug) {
+                        console.warn(`[OzVault:tokenizer] ${message}`);
+                    }
+                    break;
+                }
             }
         }
         /**
@@ -2029,6 +2152,7 @@
             }
             const newSessionId = uuid();
             (_a = this._onWaxRefresh) === null || _a === void 0 ? void 0 : _a.call(this);
+            const refreshStartMs = Date.now();
             this.log('wax key refresh started');
             this._waxRefreshing = this._storedFetchWaxKey(newSessionId)
                 .then(newWaxKey => {
@@ -2041,12 +2165,12 @@
                     this._tokenizeSuccessCount = 0;
                 }
                 if (!this._destroyed && this.tokenizerReady) {
-                    this.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey: newWaxKey });
+                    this.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey: newWaxKey, debug: this._debug });
                 }
-                this.log('wax key refresh succeeded');
+                this.log('wax key refresh succeeded', { durationMs: Date.now() - refreshStartMs });
             })
                 .catch((err) => {
-                this.log('wax key refresh failed', { error: err instanceof Error ? err.message : String(err) });
+                this.log('wax key refresh failed', { error: err instanceof Error ? err.message : String(err), durationMs: Date.now() - refreshStartMs });
                 throw err;
             })
                 .finally(() => {