@qrlwallet/connect 3.1.1 → 3.3.0

package/dist/index.js

@@ -51,6 +51,7 @@ __export(index_exports, {
   SCHEME_VERSION_TYPED: () => SCHEME_VERSION_TYPED,
   SocketClient: () => SocketClient,
   UNRESTRICTED_METHODS: () => UNRESTRICTED_METHODS,
+  attemptWalletRedirect: () => attemptWalletRedirect,
   bytesToHex: () => bytesToHex,
   cidFromString: () => cidFromString,
   cidRandom: () => cidRandom,
@@ -630,6 +631,7 @@ var KeyExchange = class extends import_eventemitter3.default {
 var import_socket = require("socket.io-client");
 var import_eventemitter32 = __toESM(require("eventemitter3"));
 var PENDING_JOIN_TIMEOUT_MS = 2e4;
+var SEND_FLUSH_TIMEOUT_MS = 600;
 var SocketClient = class extends import_eventemitter32.default {
   constructor(relayUrl, clientType) {
     super();
@@ -820,6 +822,48 @@ var SocketClient = class extends import_eventemitter32.default {
       );
     });
   }
+  /**
+   * Emit an event and resolve once the relay acks it, or after a bounded
+   * flush window. Lets a caller await transmission before tearing the
+   * socket down.
+   */
+  flushEmit(event, payload) {
+    return new Promise((resolve) => {
+      if (!this.socket?.connected) {
+        resolve();
+        return;
+      }
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      };
+      const timer = setTimeout(done, SEND_FLUSH_TIMEOUT_MS);
+      this.socket.emit(event, payload, () => {
+        clearTimeout(timer);
+        done();
+      });
+    });
+  }
+  /**
+   * Explicitly terminate the channel on the relay (durable tombstone), as
+   * opposed to the transient leaveChannel(). Used when the session is dead
+   * in a way an encrypted TERMINATE cannot communicate (AEAD desync: the
+   * peer could not open it). Resolves once the close is flushed or the
+   * bounded window elapses, so the caller can safely disconnect afterwards.
+   */
+  closeChannel() {
+    const channelId = this.channelId;
+    this.channelId = null;
+    if (this.pendingJoin) {
+      clearTimeout(this.pendingJoin.watchdog);
+      this.pendingJoin.reject(new Error("Channel closed before join completed"));
+      this.pendingJoin = null;
+    }
+    if (!this.socket?.connected || !channelId) return Promise.resolve();
+    return this.flushEmit("close_channel", { channelId });
+  }
   /**
    * Leave the current channel.
    */
@@ -1120,11 +1164,13 @@ var _ConnectionManager = class _ConnectionManager extends import_eventemitter33.
     this.connectedAccounts = [];
     this.unresponsiveTimer = null;
     this.reconnectProbeTimer = null;
+    this.restoreInFlight = null;
     this.failedReconnects = 0;
     this.walletPresent = false;
     this.pendingRestore = null;
     this.messageQueue = Promise.resolve();
     this.outboundQueue = Promise.resolve();
+    this.consecutiveDecryptFailures = 0;
     this.dappMetadata = options.dappMetadata;
     this.relayUrl = options.relayUrl ?? DEFAULT_RELAY_URL;
     this.chainId = options.chainId ?? "0x0";
@@ -1243,6 +1289,7 @@ var _ConnectionManager = class _ConnectionManager extends import_eventemitter33.
     this.clearReconnectProbe();
     this.pendingRestore = null;
     this.walletPresent = false;
+    this.consecutiveDecryptFailures = 0;
     if (this.keyExchange) {
       this.keyExchange.reset();
     } else {
@@ -1281,9 +1328,18 @@ var _ConnectionManager = class _ConnectionManager extends import_eventemitter33.
    * Returns false if there is nothing to restore.
    */
   async reconnect() {
+    if (this.restoreInFlight) return this.restoreInFlight;
+    const task = this.reconnectNow().finally(() => {
+      this.restoreInFlight = null;
+    });
+    this.restoreInFlight = task;
+    return task;
+  }
+  async reconnectNow() {
     if (!this.pendingRestore) return false;
     this.setStatus("reconnecting" /* RECONNECTING */);
     this.walletPresent = false;
+    this.consecutiveDecryptFailures = 0;
     try {
       const session = await KeyExchange.sessionFromPersisted(this.pendingRestore.keyExchange);
       this.keyExchange = new KeyExchange(true, session);
@@ -1359,15 +1415,53 @@ var _ConnectionManager = class _ConnectionManager extends import_eventemitter33.
       }
     }
   }
+  /**
+   * Make sure the socket is open and joined to the paired session's channel
+   * so an outbound request can be routed - or relay-buffered if the wallet is
+   * currently absent (its socket dies within seconds of the app
+   * backgrounding; the relay holds channel traffic for it). Revives the
+   * socket after a probe-timeout teardown and hydrates a cold stored
+   * session. Returns false when there is no session to revive (never paired,
+   * explicit disconnect, or the channel was tombstoned).
+   */
+  async ensureChannelJoined() {
+    if (this.keyExchange?.areKeysExchanged()) {
+      if (this.socketClient.isConnected() && this.socketClient.getChannelId()) {
+        return true;
+      }
+      this.setStatus("reconnecting" /* RECONNECTING */);
+      this.walletPresent = false;
+      return this.joinAndSettle();
+    }
+    if (this.pendingRestore) {
+      return this.reconnect();
+    }
+    return false;
+  }
+  /**
+   * True while a pairing exists (handshake complete, session keys in
+   * memory), even when the wallet's socket is momentarily out of the
+   * channel. Survives the reconnect-probe teardown; false after an explicit
+   * disconnect or a relay tombstone.
+   */
+  isPaired() {
+    return this.keyExchange?.areKeysExchanged() ?? false;
+  }
+  /** True while the relay roster last showed the wallet in the channel. */
+  isWalletPresent() {
+    return this.walletPresent;
+  }
   /**
    * A session was terminated for good (wallet sent a relay 'close', or the
    * join ack reported a tombstone). Clear local state and surface
    * DISCONNECTED so the consumer drops to a fresh-pairing UI.
    */
   handleSessionTerminated() {
+    this.emit("session_terminated");
     this.clearReconnectProbe();
     this.clearUnresponsiveTimer();
     this.walletPresent = false;
+    this.consecutiveDecryptFailures = 0;
     this.pendingRestore = null;
     this.keyExchange = null;
     this.socketClient.leaveChannel();
@@ -1396,22 +1490,28 @@ var _ConnectionManager = class _ConnectionManager extends import_eventemitter33.
     }
   }
   /**
-   * Send a JSON-RPC request to the wallet (async, fire-and-forget).
+   * Send a JSON-RPC request to the wallet. Returns the outbound send promise
+   * (settled on the relay's ack) so callers that must sequence on delivery -
+   * e.g. the provider's wallet-wake redirect, which cannot navigate away
+   * before the ciphertext reaches the relay - can await it. Callers may also
+   * ignore it: failures are logged here either way.
    */
   sendJsonRpc(request) {
     if (!this.keyExchange?.areKeysExchanged()) {
       throw new Error("Not connected: key exchange not complete");
     }
-    this.sendEncrypted({
+    const sent = this.sendEncrypted({
       type: "jsonrpc" /* JSONRPC */,
       jsonrpc: "2.0",
       id: request.id,
       method: request.method,
       params: request.params
-    }).catch((err) => {
+    });
+    sent.catch((err) => {
       error("ConnectionManager", "Failed to send JSON-RPC:", err);
     });
     this.startUnresponsiveTimer();
+    return sent;
   }
   getStatus() {
     return this.status;
@@ -1525,8 +1625,19 @@ var _ConnectionManager = class _ConnectionManager extends import_eventemitter33.
       }
     }
     if (typeof message === "string" && this.keyExchange?.areKeysExchanged()) {
+      let decrypted;
+      try {
+        decrypted = await this.keyExchange.decryptMessage(message);
+      } catch (err) {
+        error("ConnectionManager", "Failed to decrypt message:", err);
+        this.consecutiveDecryptFailures++;
+        if (this.consecutiveDecryptFailures >= _ConnectionManager.MAX_DECRYPT_FAILURES) {
+          await this.teardownDesyncedSession();
+        }
+        return;
+      }
+      this.consecutiveDecryptFailures = 0;
       try {
-        const decrypted = await this.keyExchange.decryptMessage(message);
         await this.persistSession();
         const parsed = JSON.parse(decrypted);
         if (isRecord(parsed)) {
@@ -1535,10 +1646,24 @@ var _ConnectionManager = class _ConnectionManager extends import_eventemitter33.
           warn("ConnectionManager", "Dropping non-object decrypted payload");
         }
       } catch (err) {
-        error("ConnectionManager", "Failed to decrypt message:", err);
+        error("ConnectionManager", "Failed to handle decrypted message:", err);
       }
     }
   }
+  /**
+   * The receive stream is cryptographically unrecoverable: the peer's send
+   * counter is ahead of our recv counter for good (relay buffer TTL/cap
+   * dropped a ciphertext), so every future message would fail its tag.
+   * An encrypted TERMINATE cannot communicate this (the desynced peer could
+   * not open it either); tombstone the channel on the relay instead so the
+   * wallet learns the pairing is dead even if it only re-joins later, then
+   * clear local state and surface the standard terminated teardown.
+   */
+  async teardownDesyncedSession() {
+    warn("ConnectionManager", "AEAD stream desynced beyond recovery; terminating session");
+    await this.socketClient.closeChannel();
+    this.handleSessionTerminated();
+  }
   async handleSynAck(msg) {
     if (!this.keyExchange) return;
     this.setStatus("key_exchange" /* KEY_EXCHANGE */);
@@ -1592,6 +1717,7 @@ var _ConnectionManager = class _ConnectionManager extends import_eventemitter33.
       }
       case "terminate" /* TERMINATE */: {
         log("ConnectionManager", "Received terminate from wallet");
+        this.emit("session_terminated");
         void this.disconnect();
         break;
       }
@@ -1711,6 +1837,12 @@ var _ConnectionManager = class _ConnectionManager extends import_eventemitter33.
   }
 };
 _ConnectionManager.MAX_RECONNECT_FAILURES = 5;
+// Nonces derive from the recv counter and there is no gap tolerance, so a
+// genuinely desynced stream (peer advanced past us, e.g. the relay's
+// buffer TTL dropped a ciphertext) fails EVERY subsequent open. Two in a
+// row cannot happen on a healthy stream; requiring the second guards
+// against a one-off injected junk ciphertext killing a live session.
+_ConnectionManager.MAX_DECRYPT_FAILURES = 2;
 var ConnectionManager = _ConnectionManager;
 
 // src/utils/platform.ts
@@ -1724,6 +1856,41 @@ function getAppStoreUrl() {
   }
   return "https://apps.apple.com/app/myqrlwallet/id6742219498";
 }
+function attemptWalletRedirect(uri, timeoutMs = 1800) {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return Promise.resolve(false);
+  }
+  if (!uri.trim().toLowerCase().startsWith("qrlconnect:")) {
+    return Promise.resolve(false);
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (opened) => {
+      if (settled) return;
+      settled = true;
+      document.removeEventListener("visibilitychange", onVisibility);
+      window.removeEventListener("pagehide", onHide);
+      window.clearTimeout(timer);
+      resolve(opened);
+    };
+    const onVisibility = () => {
+      if (document.visibilityState === "hidden") finish(true);
+    };
+    const onHide = () => {
+      finish(true);
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    window.addEventListener("pagehide", onHide);
+    const timer = window.setTimeout(() => {
+      finish(false);
+    }, timeoutMs);
+    try {
+      window.location.href = uri;
+    } catch {
+      finish(false);
+    }
+  });
+}
 
 // src/QRLConnectProvider.ts
 var QRL_CONNECT_PROVIDER_INFO = {
@@ -1733,6 +1900,16 @@ var QRL_CONNECT_PROVIDER_INFO = {
 };
 var EIP6963_ANNOUNCE_EVENT = "eip6963:announceProvider";
 var EIP6963_REQUEST_EVENT = "eip6963:requestProvider";
+function isRecordObj(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function parseInflightRecord(v) {
+  if (!isRecordObj(v)) return null;
+  const { id, method, ts } = v;
+  if (typeof id !== "string" && typeof id !== "number") return null;
+  if (typeof method !== "string" || typeof ts !== "number") return null;
+  return { id, method, ts };
+}
 var QRLConnectProvider = class extends import_eventemitter34.default {
   constructor(options) {
     super();
@@ -1741,6 +1918,7 @@ var QRLConnectProvider = class extends import_eventemitter34.default {
     this.eip6963RequestListener = null;
     this.resumeListener = null;
     this.resumeDebounce = null;
+    this.orphanedRequests = /* @__PURE__ */ new Map();
     // Random per-instance prefix keeps request ids unique across page loads.
     // A bare counter restarts at 1 on reload, and the relay buffers messages
     // for 5 minutes, so a stale buffered response could otherwise be matched
@@ -1749,6 +1927,10 @@ var QRLConnectProvider = class extends import_eventemitter34.default {
     this.requestCounter = 0;
     this.isQRLConnect = true;
     this.options = options;
+    this.inflightKey = `${options.storageKey ?? `${STORAGE_KEY_PREFIX}:session`}:inflight`;
+    for (const rec of this.readInflight()) {
+      this.orphanedRequests.set(rec.id, { method: rec.method });
+    }
     if (options.debug) {
       setDebug(true);
     }
@@ -1861,6 +2043,16 @@ var QRLConnectProvider = class extends import_eventemitter34.default {
     this.connectionManager.on("jsonrpc_response", (response) => {
       const pending = this.pendingRequests.get(response.id);
       if (!pending) {
+        const orphan = this.orphanedRequests.get(response.id);
+        if (orphan) {
+          this.settleInflight(response.id);
+          this.emit("late_response", {
+            id: response.id,
+            method: orphan.method,
+            ...response.error ? { error: response.error } : { result: response.result }
+          });
+          return;
+        }
         warn("Provider", `No pending request for id ${response.id}`);
         return;
       }
@@ -1889,6 +2081,13 @@ var QRLConnectProvider = class extends import_eventemitter34.default {
       }
       this.pendingRequests.clear();
     });
+    this.connectionManager.on("session_terminated", () => {
+      for (const [, pending] of this.pendingRequests) {
+        pending.reject(new Error("Session terminated by wallet"));
+      }
+      this.pendingRequests.clear();
+      this.clearAllInflight();
+    });
   }
   /**
    * Generate a connection URI for QR code display or deep link redirect.
@@ -1925,7 +2124,13 @@ var QRLConnectProvider = class extends import_eventemitter34.default {
       throw new Error(`Unsupported method: ${method}`);
     }
     if (this.connectionManager.getStatus() !== "connected" /* CONNECTED */) {
-      throw new Error("Not connected to QRL Wallet");
+      if (method === "qrl_requestAccounts" && this.connectionManager.isPaired() && this.connectionManager.getAccounts().length > 0) {
+        return this.connectionManager.getAccounts();
+      }
+      const joined = await this.connectionManager.ensureChannelJoined();
+      if (!joined) {
+        throw new Error("Not connected to QRL Wallet");
+      }
     }
     const id = `${this.requestIdPrefix}-${++this.requestCounter}`;
     return new Promise((resolve, reject) => {
@@ -1948,20 +2153,109 @@ var QRLConnectProvider = class extends import_eventemitter34.default {
       const originalReject = pending.reject;
       pending.resolve = (result) => {
         clearTimeout(timeout);
+        this.settleInflight(id);
         originalResolve(result);
       };
       pending.reject = (error2) => {
         clearTimeout(timeout);
+        this.settleInflight(id);
         originalReject(error2);
       };
-      this.connectionManager.sendJsonRpc({
+      if (RESTRICTED_METHODS.has(method)) {
+        this.persistInflight(id, method);
+      }
+      const sent = this.connectionManager.sendJsonRpc({
         jsonrpc: "2.0",
         id,
         method,
         params
       });
+      sent.catch((err) => {
+        const failed = this.pendingRequests.get(id);
+        if (!failed) return;
+        this.pendingRequests.delete(id);
+        failed.reject(err instanceof Error ? err : new Error(String(err)));
+      });
+      if (this.shouldRedirectToWallet(method)) {
+        void sent.then(
+          () => attemptWalletRedirect(this.walletWakeUri()),
+          () => void 0
+        );
+      }
     });
   }
+  /**
+   * Redirect only for calls the user must approve, on mobile, and only when
+   * the wallet is actually absent from the channel: right after pairing its
+   * socket lingers and a pointless app flash would be jarring.
+   *
+   * qrl_requestAccounts is excluded even though it is restricted: dApps call
+   * it on page load to restore a session, so it can run with no user gesture
+   * (an unsolicited "Open in MyQRLWallet?" sheet on load) and pairing UIs
+   * already own their own deep-link step.
+   */
+  shouldRedirectToWallet(method) {
+    return this.options.walletRedirectOnRequest !== false && RESTRICTED_METHODS.has(method) && method !== "qrl_requestAccounts" && isMobileBrowser() && !this.connectionManager.isWalletPresent();
+  }
+  // ── In-flight persistence (survive the return-redirect reload) ──────
+  readInflight() {
+    if (typeof localStorage === "undefined") return [];
+    try {
+      const raw = localStorage.getItem(this.inflightKey);
+      if (!raw) return [];
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed)) return [];
+      const now = Date.now();
+      const records = [];
+      for (const v of parsed) {
+        const rec = parseInflightRecord(v);
+        if (rec && now - rec.ts <= REQUEST_TIMEOUT_MS) records.push(rec);
+      }
+      return records;
+    } catch {
+      return [];
+    }
+  }
+  writeInflight(records) {
+    if (typeof localStorage === "undefined") return;
+    try {
+      if (records.length === 0) {
+        localStorage.removeItem(this.inflightKey);
+      } else {
+        localStorage.setItem(this.inflightKey, JSON.stringify(records));
+      }
+    } catch {
+    }
+  }
+  persistInflight(id, method) {
+    const records = this.readInflight().filter((r) => r.id !== id);
+    records.push({ id, method, ts: Date.now() });
+    this.writeInflight(records);
+  }
+  settleInflight(id) {
+    this.orphanedRequests.delete(id);
+    this.writeInflight(this.readInflight().filter((r) => r.id !== id));
+  }
+  clearAllInflight() {
+    this.orphanedRequests.clear();
+    this.writeInflight([]);
+  }
+  /**
+   * Wake URI for the wallet app. Carries no pairing payload: the app
+   * foregrounds on any `qrlconnect:` URL and re-joins its sessions (draining
+   * the buffered request); the cid lets a future wallet jump straight to the
+   * right approval.
+   *
+   * MUST stay query-only (no host/path). The mobile app routes deep links
+   * with expo-router, which maps anything after the scheme to an in-app
+   * route: `qrlconnect://resume?...` lands on the "+not-found" screen and
+   * unmounts the WebView, so the wake achieves nothing. The hostless form
+   * routes to the WebView tab exactly like the pairing URIs
+   * (`qrlconnect://?q=...`), which is the whole point of the wake.
+   */
+  walletWakeUri() {
+    return `qrlconnect://?wake=${encodeURIComponent(this.connectionManager.getChannelId())}`;
+  }
   /**
    * Get the current connection status.
    */
@@ -1992,6 +2286,19 @@ var QRLConnectProvider = class extends import_eventemitter34.default {
   hasStoredSession() {
     return this.connectionManager.hasStoredSession();
   }
+  /**
+   * True while a pairing exists (keys exchanged), even when the wallet app
+   * is backgrounded and its socket is out of the channel. Combine with
+   * getStatus() to tell "wallet away, session intact" (paired + WAITING)
+   * apart from "waiting for a first scan" in pairing UIs.
+   */
+  isPaired() {
+    return this.connectionManager.isPaired();
+  }
+  /** True while the wallet is actually present in the relay channel. */
+  isWalletPresent() {
+    return this.connectionManager.isWalletPresent();
+  }
   /**
    * Reset the connection and start a fresh pairing with a new channel.
    * Use this when the user wants to create a new connection instead of
@@ -2002,6 +2309,7 @@ var QRLConnectProvider = class extends import_eventemitter34.default {
       pending.reject(new Error("Connection reset"));
     }
     this.pendingRequests.clear();
+    this.clearAllInflight();
     await this.connectionManager.resetForNewChannel();
     return this.getConnectionURI();
   }
@@ -2016,6 +2324,7 @@ var QRLConnectProvider = class extends import_eventemitter34.default {
       pending.reject(new Error("Disconnected"));
     }
     this.pendingRequests.clear();
+    this.clearAllInflight();
     this.teardownResumeListeners();
     await this.connectionManager.disconnect();
   }
@@ -2406,6 +2715,7 @@ function verifyTypedData({ signature, publicKey, payload }) {
   SCHEME_VERSION_TYPED,
   SocketClient,
   UNRESTRICTED_METHODS,
+  attemptWalletRedirect,
   bytesToHex,
   cidFromString,
   cidRandom,