@ozura/elements 1.2.1 → 1.2.3

package/dist/oz-elements.esm.js

@@ -198,7 +198,7 @@ function normalizeCommonVaultError(msg) {
     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;
@@ -218,7 +218,7 @@ function normalizeVaultError(raw) {
     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')) {
@@ -376,7 +376,7 @@ function sanitizeOptions(options) {
  * 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;
@@ -384,6 +384,7 @@ class OzElement {
         this._loadTimer = null;
         this.pendingMessages = [];
         this.handlers = new Map();
+        this.debug = false;
         this.elementType = elementType;
         this.options = sanitizeOptions(options);
         this.vaultId = vaultId;
@@ -392,6 +393,8 @@ class OzElement {
         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() {
@@ -431,11 +434,17 @@ class OzElement {
             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 : '';
@@ -547,9 +556,14 @@ class OzElement {
      * 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 ───────────────────────────────────────────────────
     /**
@@ -586,7 +600,7 @@ class OzElement {
                 }
                 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);
@@ -700,13 +714,14 @@ function validateEmail(email) {
 // ─── 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). */
@@ -909,12 +924,12 @@ const PROTOCOL_VERSION = 1;
  *
  * @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'),
  * });
  */
@@ -952,7 +967,22 @@ function createSessionFetcher(url) {
                 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
@@ -970,10 +1000,19 @@ function createSessionFetcher(url) {
 }
 
 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";
 /**
@@ -983,16 +1022,10 @@ const DEFAULT_FRAME_BASE_URL = "https://elements.ozura.com";
  * 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');
@@ -1038,6 +1071,11 @@ class OzVault {
         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);
@@ -1146,7 +1184,7 @@ class OzVault {
         // 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;
@@ -1228,7 +1266,12 @@ class OzVault {
             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;
@@ -1311,7 +1354,6 @@ class OzVault {
                 this.sendToTokenizer({
                     type: 'OZ_BANK_TOKENIZE',
                     requestId,
-                    waxKey: this.waxKey,
                     tokenizationSessionId: this.tokenizationSessionId,
                     pubKey: this.pubKey,
                     firstName: options.firstName.trim(),
@@ -1319,7 +1361,10 @@ class OzVault {
                     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);
@@ -1403,7 +1448,11 @@ class OzVault {
         }
         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.
@@ -1428,7 +1477,6 @@ class OzVault {
                 this.sendToTokenizer({
                     type: 'OZ_TOKENIZE',
                     requestId,
-                    waxKey: this.waxKey,
                     tokenizationSessionId: this.tokenizationSessionId,
                     pubKey: this.pubKey,
                     firstName,
@@ -1441,7 +1489,10 @@ class OzVault {
                 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);
@@ -1494,6 +1545,7 @@ class OzVault {
             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.'));
             });
@@ -1501,6 +1553,7 @@ class OzVault {
             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.'));
             });
@@ -1675,7 +1728,7 @@ class OzVault {
         }
     }
     handleMessage(event) {
-        var _a;
+        var _a, _b;
         if (this._destroyed)
             return;
         // Only accept messages from our frame origin (defense in depth; prevents
@@ -1690,6 +1743,15 @@ class OzVault {
             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) {
@@ -1707,6 +1769,23 @@ class OzVault {
                     }
                     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);
@@ -1751,7 +1830,7 @@ class OzVault {
         }
     }
     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) {
@@ -1769,9 +1848,10 @@ class OzVault {
                 // 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) {
@@ -1797,6 +1877,7 @@ class OzVault {
                     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,
@@ -1828,7 +1909,7 @@ class OzVault {
                     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) {
@@ -1846,6 +1927,17 @@ class OzVault {
                                 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 }));
@@ -1854,14 +1946,16 @@ class OzVault {
                                 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);
@@ -1878,68 +1972,80 @@ class OzVault {
                                 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': {
@@ -1975,6 +2081,23 @@ class OzVault {
                 }
                 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;
+            }
         }
     }
     /**
@@ -2023,6 +2146,7 @@ class OzVault {
         }
         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 => {
@@ -2035,12 +2159,12 @@ class OzVault {
                 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(() => {