@swype-org/deposit 0.3.16 → 0.3.20

package/README.md

@@ -98,10 +98,20 @@ const deposit = new Deposit({
   containerElement: document.getElementById('deposit-root')!,
   signerTimeoutMs: 15_000,
   flowTimeoutMs: 300_000,
+  enableFullWidget: true,
   debug: false,
 });
 ```
 
+### `enableFullWidget`
+
+Controls whether the hosted flow may show the full widget (the Deposit Options
+entry screen for unauthenticated users). Defaults to `true`. The full widget
+only appears when this option is enabled **and** the merchant's backend config
+has it enabled — disabling either turns it off. Set it to `false` to force the
+hosted flow straight to the standard deposit flow regardless of merchant
+config.
+
 ## Error Handling
 
 Every error is a `DepositError` with a machine-readable `code`:
@@ -164,6 +174,27 @@ import type {
 import type { DepositErrorCode } from '@swype-org/deposit';
 ```
 
+## Security & content integrity
+
+The deposit UI loads live from `https://pay.blink.cash` every render — the
+standard model for embedded payment UIs (it lets us ship security/fraud fixes
+instantly). We do not version-pin the iframe; instead:
+
+- **Verifiable build manifest** — every deploy publishes
+  [`https://pay.blink.cash/manifest.json`](https://pay.blink.cash/manifest.json)
+  with the build version, source commit, and a SHA-256 of every served file, so
+  you can confirm exactly what we serve.
+- **Lock the iframe origin** — add a CSP to your page so the iframe can only ever
+  load from Swype:
+
+  ```
+  Content-Security-Policy: frame-src https://pay.blink.cash; script-src 'self';
+  ```
+
+See [docs/iframe-security.md](../docs/iframe-security.md) for the full security
+model (CSP, postMessage hardening, Privy origin allow-listing, passkey
+delegation, and SRI rationale).
+
 ## Backward Compatibility
 
 The previous `Checkout`-named symbols are re-exported as deprecated aliases:

package/dist/{chunk-WD6DVQHT.js → chunk-VMXCXXVN.js}

@@ -524,15 +524,19 @@ var STYLES = `
 [data-blink-overlay][data-blink-mobile-sheet][data-blink-closing] [data-blink-container]{opacity:1;animation:blink-slide-down-full ${CLOSE_DURATION_MS}ms ease-in forwards}
 @media(max-width:${MOBILE_SHEET_MAX_VIEWPORT_PX}px){[data-blink-overlay]{align-items:flex-end;touch-action:none;overscroll-behavior:contain}[data-blink-container]{width:100%;max-width:100%;height:79vh;border-radius:24px 24px 0 0;box-shadow:0 -8px 40px rgba(0,0,0,.25);animation:blink-slide-up-full .35s cubic-bezier(.32,.72,0,1);padding-bottom:env(safe-area-inset-bottom,0px)}[data-blink-overlay][data-blink-closing] [data-blink-container]{opacity:1;animation:blink-slide-down-full ${CLOSE_DURATION_MS}ms ease-in forwards}}
 `;
-function createIframe(url, containerElement) {
+function createIframe(url, containerElement, options) {
   ensureStyles();
   let closed = false;
+  let hidden = options?.hidden === true;
   let closeCallback = null;
   const overlay = document.createElement("div");
   overlay.setAttribute("data-blink-overlay", "");
   if (shouldUseMobileSheetLayout()) {
     overlay.setAttribute("data-blink-mobile-sheet", "");
   }
+  if (hidden) {
+    overlay.style.display = "none";
+  }
   const container = document.createElement("div");
   container.setAttribute("data-blink-container", "");
   const iframe = document.createElement("iframe");
@@ -558,8 +562,8 @@ function createIframe(url, containerElement) {
   };
   attachBridge();
   iframe.addEventListener("load", attachBridge);
-  const savedOverflow = document.body.style.overflow;
-  document.body.style.overflow = "hidden";
+  let savedOverflow = "";
+  let scrollLocked = false;
   const onBackdropClick = (event) => {
     if (event.target === overlay) triggerClose();
   };
@@ -569,15 +573,29 @@ function createIframe(url, containerElement) {
   const onTouchMove = (event) => {
     if (event.target === overlay) event.preventDefault();
   };
-  overlay.addEventListener("click", onBackdropClick);
-  overlay.addEventListener("touchmove", onTouchMove, { passive: false });
-  document.addEventListener("keydown", onKeyDown);
+  function lockScroll() {
+    if (scrollLocked) return;
+    scrollLocked = true;
+    savedOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+  }
+  function attachDismissalListeners() {
+    overlay.addEventListener("click", onBackdropClick);
+    overlay.addEventListener("touchmove", onTouchMove, { passive: false });
+    document.addEventListener("keydown", onKeyDown);
+  }
+  if (!hidden) {
+    lockScroll();
+    attachDismissalListeners();
+  }
   function removeListeners() {
     overlay.removeEventListener("click", onBackdropClick);
     overlay.removeEventListener("touchmove", onTouchMove);
     document.removeEventListener("keydown", onKeyDown);
   }
   function unlockScroll() {
+    if (!scrollLocked) return;
+    scrollLocked = false;
     document.body.style.overflow = savedOverflow;
   }
   function triggerClose() {
@@ -615,6 +633,21 @@ function createIframe(url, containerElement) {
     isClosed() {
       return closed;
     },
+    isHidden() {
+      return hidden;
+    },
+    reveal() {
+      if (closed || !hidden) return;
+      hidden = false;
+      if (shouldUseMobileSheetLayout()) {
+        overlay.setAttribute("data-blink-mobile-sheet", "");
+      } else {
+        overlay.removeAttribute("data-blink-mobile-sheet");
+      }
+      overlay.style.display = "";
+      lockScroll();
+      attachDismissalListeners();
+    },
     onClose(callback) {
       closeCallback = callback;
     },
@@ -786,6 +819,13 @@ function buildSignerRequest(request, webviewBaseUrl) {
 
 // src/checkout.ts
 var DEFAULT_WEBVIEW_BASE_URL = "https://pay.blink.cash";
+var SANDBOX_WEBVIEW_BASE_URL = "https://pay-sandbox.blink.cash";
+var IFRAME_READY_TIMEOUT_MS = 2e3;
+var WARM_IFRAME_READY_TIMEOUT_MS = 6e4;
+function resolveWebviewBaseUrl(config) {
+  if (config.webviewBaseUrl) return config.webviewBaseUrl;
+  return config.environment === "sandbox" ? SANDBOX_WEBVIEW_BASE_URL : DEFAULT_WEBVIEW_BASE_URL;
+}
 var Deposit = class {
   config;
   iframe = null;
@@ -798,6 +838,9 @@ var Deposit = class {
   _error = null;
   flowTimer = null;
   lastSignerResponse = null;
+  warmIframe = null;
+  warmIframeReady = null;
+  warmIframeReadyCancel = null;
   listeners = {
     complete: /* @__PURE__ */ new Set(),
     error: /* @__PURE__ */ new Set(),
@@ -828,6 +871,93 @@ var Deposit = class {
     this.log("Deposit instance created", {
       signer: typeof config.signer === "string" ? config.signer : "<function>"
     });
+    if (config.preload !== false) {
+      this.schedulePreload();
+    }
+  }
+  /**
+   * Warm up the hosted payment flow in a hidden iframe so `requestDeposit`
+   * opens an already-loaded page (JS bundle, auth session restore, and —
+   * when {@link DepositConfig.merchantId} is set — merchant config prefetch
+   * all happen in the background).
+   *
+   * Runs automatically after construction unless `preload: false`; call it
+   * manually to control the timing (e.g. on deposit-button hover). No-op
+   * when a warm iframe already exists or a deposit flow is active.
+   */
+  preload() {
+    if (this.destroyed || this.isActive) return;
+    if (this.warmIframe && !this.warmIframe.isClosed()) return;
+    if (typeof document === "undefined" || typeof window === "undefined") return;
+    const webviewBaseUrl = resolveWebviewBaseUrl(this.config);
+    this.hostedOrigin = this.config.hostedFlowOrigin ?? new URL(webviewBaseUrl).origin;
+    const preloadUrl = this.buildPreloadUrl(webviewBaseUrl);
+    const iframe = createIframe(preloadUrl, this.config.containerElement, { hidden: true });
+    const ready = this.waitForIframeReady(iframe, WARM_IFRAME_READY_TIMEOUT_MS);
+    this.warmIframe = iframe;
+    this.warmIframeReady = ready.promise;
+    this.warmIframeReadyCancel = ready.cancel;
+    this.log("Warm-up iframe created", { url: preloadUrl });
+  }
+  // Defer the automatic warm-up until the host page has finished its own
+  // load and the main thread is idle — constructing a Deposit instance must
+  // never slow the merchant page down.
+  schedulePreload() {
+    if (typeof window === "undefined" || typeof document === "undefined") return;
+    const start = () => {
+      if (!this.destroyed && !this.isActive) this.preload();
+    };
+    const whenIdle = () => {
+      const w = window;
+      if (typeof w.requestIdleCallback === "function") {
+        w.requestIdleCallback(start, { timeout: 3e3 });
+      } else {
+        setTimeout(start, 250);
+      }
+    };
+    if (document.readyState === "complete") {
+      whenIdle();
+    } else {
+      window.addEventListener("load", whenIdle, { once: true });
+    }
+  }
+  buildPreloadUrl(webviewBaseUrl) {
+    const preloadUrl = new URL(webviewBaseUrl);
+    preloadUrl.searchParams.set("preload", "true");
+    if (this.config.merchantId) {
+      preloadUrl.searchParams.set("merchantId", this.config.merchantId);
+    }
+    this.applyFullWidgetParam(preloadUrl);
+    return preloadUrl.toString();
+  }
+  /**
+   * Detach the warm iframe for use by a starting flow. Returns null (and
+   * cleans up) when there is none or it was closed in the meantime.
+   */
+  takeWarmIframe() {
+    const iframe = this.warmIframe;
+    const ready = this.warmIframeReady;
+    const cancelReady = this.warmIframeReadyCancel ?? (() => {
+    });
+    this.warmIframe = null;
+    this.warmIframeReady = null;
+    this.warmIframeReadyCancel = null;
+    if (!iframe || !ready) return null;
+    if (iframe.isClosed()) {
+      cancelReady();
+      iframe.destroy();
+      return null;
+    }
+    return { iframe, ready, cancelReady };
+  }
+  discardWarmIframe() {
+    this.warmIframeReadyCancel?.();
+    this.warmIframeReadyCancel = null;
+    this.warmIframeReady = null;
+    if (this.warmIframe) {
+      this.warmIframe.destroy();
+      this.warmIframe = null;
+    }
   }
   /**
    * Open the hosted payment flow for the given deposit.
@@ -915,9 +1045,10 @@ var Deposit = class {
   /** Tear down the instance and release all resources. */
   destroy() {
     this.log("destroy() called");
+    this.destroyed = true;
     this.cleanup();
+    this.discardWarmIframe();
     this.setStatus("idle");
-    this.destroyed = true;
     for (const set of Object.values(this.listeners)) {
       set.clear();
     }
@@ -931,6 +1062,17 @@ var Deposit = class {
       console.debug(`[BlinkDeposit] ${message}`);
     }
   }
+  /**
+   * Appends `enableFullWidget=false` to the hosted-flow URL when the merchant
+   * integration disables the full widget. Absence of the param means enabled
+   * (the default) — the hosted flow ANDs this with the merchant's backend
+   * config, so the full widget renders only when both allow it.
+   */
+  applyFullWidgetParam(url) {
+    if (this.config.enableFullWidget === false) {
+      url.searchParams.set("enableFullWidget", "false");
+    }
+  }
   setStatus(status) {
     if (this._status === status) return;
     this.log(`Status: ${this._status} \u2192 ${status}`);
@@ -939,15 +1081,35 @@ var Deposit = class {
   }
   async runSignerFlow(request, requestId, onComplete, onError) {
     try {
-      const webviewBaseUrl = this.config.webviewBaseUrl ?? DEFAULT_WEBVIEW_BASE_URL;
+      const webviewBaseUrl = resolveWebviewBaseUrl(this.config);
       this.hostedOrigin = this.config.hostedFlowOrigin ?? new URL(webviewBaseUrl).origin;
       this.log("Calling signer", {
         signer: typeof this.config.signer === "string" ? this.config.signer : "<function>"
       });
       const signerRequest = buildSignerRequest(request, webviewBaseUrl);
-      const preloadUrl = new URL(webviewBaseUrl);
-      preloadUrl.searchParams.set("preload", "true");
-      const preloadIframe = createIframe(preloadUrl.toString(), this.config.containerElement);
+      let preloadIframe;
+      let iframeReadyPromise;
+      const warm = this.takeWarmIframe();
+      if (warm) {
+        warm.iframe.reveal();
+        preloadIframe = warm.iframe;
+        iframeReadyPromise = Promise.race([
+          warm.ready,
+          new Promise(
+            (resolve) => setTimeout(() => resolve(false), IFRAME_READY_TIMEOUT_MS)
+          )
+        ]).then((ready) => {
+          warm.cancelReady();
+          return ready;
+        });
+        this.log("Reusing warm preload iframe");
+      } else {
+        preloadIframe = createIframe(
+          this.buildPreloadUrl(webviewBaseUrl),
+          this.config.containerElement
+        );
+        iframeReadyPromise = this.waitForIframeReady(preloadIframe).promise;
+      }
       this.iframe = preloadIframe;
       preloadIframe.onClose(() => {
         onError(
@@ -964,7 +1126,6 @@ var Deposit = class {
         signerRequest,
         this.config.signerTimeoutMs
       );
-      const iframeReadyPromise = this.waitForIframeReady(preloadIframe);
       const [signerResponse, iframeReady] = await Promise.all([
         signerPromise,
         iframeReadyPromise
@@ -996,6 +1157,7 @@ var Deposit = class {
         hostedUrl.searchParams.set("merchantId", signerResponse.merchantId);
         hostedUrl.searchParams.set("payload", signerResponse.payload);
         hostedUrl.searchParams.set("signature", signerResponse.signature);
+        this.applyFullWidgetParam(hostedUrl);
         const targetUrl = hostedUrl.toString();
         const iframeHandle = createIframe(targetUrl, this.config.containerElement);
         this.iframe = iframeHandle;
@@ -1028,24 +1190,38 @@ var Deposit = class {
       }
     }
   }
-  waitForIframeReady(iframeHandle) {
-    return new Promise((resolve) => {
+  /**
+   * Resolves true when the iframe posts `blink:iframe-ready`, false on
+   * timeout. `cancel()` settles the promise as false immediately and releases
+   * the listener + timer — used to reap the generous warm-up wait once it no
+   * longer matters (warm iframe consumed or discarded).
+   */
+  waitForIframeReady(iframeHandle, timeoutMs = IFRAME_READY_TIMEOUT_MS) {
+    let finish = () => {
+    };
+    const promise = new Promise((resolve) => {
       const handler = (event) => {
         if (event.origin !== this.hostedOrigin) return;
         if (event.source !== iframeHandle.contentWindow) return;
         if (parseIframeReady(event.data)) {
-          window.removeEventListener("message", handler);
-          clearTimeout(timeout);
-          resolve(true);
+          finish(true);
         }
       };
       window.addEventListener("message", handler);
       const timeout = setTimeout(() => {
-        window.removeEventListener("message", handler);
         this.log("Iframe ready timeout \u2014 falling back to URL params");
-        resolve(false);
-      }, 2e3);
+        finish(false);
+      }, timeoutMs);
+      let settled = false;
+      finish = (ready) => {
+        if (settled) return;
+        settled = true;
+        window.removeEventListener("message", handler);
+        clearTimeout(timeout);
+        resolve(ready);
+      };
     });
+    return { promise, cancel: () => finish(false) };
   }
   startMessageListener(iframeHandle, onComplete) {
     const handler = (event) => {
@@ -1105,6 +1281,9 @@ var Deposit = class {
     }
     this.hostedOrigin = null;
     this.lastSignerResponse = null;
+    if (!this.destroyed && this.config.preload !== false) {
+      this.schedulePreload();
+    }
   }
   emit(event, ...args) {
     for (const handler of this.listeners[event]) {
@@ -1117,6 +1296,6 @@ var Deposit = class {
 };
 var Checkout = Deposit;
 
-export { ALLOWED_RPC_METHODS, BRIDGE_PROTOCOL_VERSION, Checkout, CheckoutError, DEFAULT_WEBVIEW_BASE_URL, Deposit, DepositError, attachRpcHost, createWalletDiscoverer, getDisplayMessage, parseBridgeMessage };
-//# sourceMappingURL=chunk-WD6DVQHT.js.map
-//# sourceMappingURL=chunk-WD6DVQHT.js.map
+export { ALLOWED_RPC_METHODS, BRIDGE_PROTOCOL_VERSION, Checkout, CheckoutError, DEFAULT_WEBVIEW_BASE_URL, Deposit, DepositError, SANDBOX_WEBVIEW_BASE_URL, attachRpcHost, createWalletDiscoverer, getDisplayMessage, parseBridgeMessage };
+//# sourceMappingURL=chunk-VMXCXXVN.js.map
+//# sourceMappingURL=chunk-VMXCXXVN.js.map