@meshconnect/uwc-bridge-parent 1.4.2 → 1.5.0

package/src/BridgeParent.ts

@@ -72,6 +72,26 @@ interface ExtendedStandardWalletAdapter extends StandardWalletAdapter {
   ) => Promise<Uint8Array>
 }
 
+/**
+ * Minimal structural shape of a wallet-standard wallet's `standard:events`
+ * change stream — just enough for `subscribeSolanaWalletEvent` to observe live
+ * account switches without pulling in the full `@wallet-standard/features`
+ * types. `on('change', …)` returns an unsubscribe function (wallet-standard
+ * contract); `accounts` is the wallet's currently-authorized account set, whose
+ * first entry is the active account.
+ */
+interface StandardEventsCapableWallet {
+  accounts?: readonly { address: string }[]
+  features?: {
+    'standard:events'?: {
+      on?: (
+        event: 'change',
+        listener: (properties: { accounts?: readonly unknown[] }) => void
+      ) => () => void
+    }
+  }
+}
+
 export interface WalletStandardInfo {
   uuid: string
   name: string
@@ -139,6 +159,57 @@ export interface ParentAPI {
 
   discoverTronWallets: (injectedIds: string[]) => void
   discoverTonWallets: (jsBridgeKeys: string[]) => void
+
+  /**
+   * Attach a real listener for `eventName` on the EIP-6963 provider. Awaits the
+   * one-shot EIP-6963 discovery window before looking up the wallet by `uuid` in
+   * `eip6963Wallets`; if that misses and an optional `rdns` was supplied, falls
+   * back to matching by `rdns` (a wallet-defined identifier stable across
+   * injection contexts). Forwards every event firing to `callback` (a
+   * Comlink-proxied callback the child supplies). Resolves to a teardown that
+   * removes the listener. THROWS when neither `uuid` nor the `rdns` fallback
+   * resolves a wallet (surfaced to the child as a bridge error rather than a
+   * silent no-op); resolves to `undefined` only when the wallet IS found but
+   * exposes no `.on` to observe.
+   */
+  subscribeEip6963ProviderEvent: (
+    uuid: string,
+    eventName: 'accountsChanged' | 'chainChanged' | 'disconnect',
+    callback: (payload?: unknown) => void,
+    rdns?: string
+  ) => Promise<(() => void) | undefined>
+
+  /**
+   * Same as `subscribeEip6963ProviderEvent`, but for an injected Tron
+   * provider resolved fresh by its window path (`injectedId`) rather than a
+   * cached discovery list, since Tron providers aren't cached the same way.
+   */
+  subscribeTronProviderEvent: (
+    injectedId: string,
+    eventName: 'accountsChanged' | 'disconnect',
+    callback: (payload?: unknown) => void
+  ) => (() => void) | undefined
+
+  /**
+   * Relay a connected Solana wallet's account-change events across the
+   * bridge. `walletId` is the SAME id `walletStandardWallets[].uuid`
+   * publishes (see `generateWalletId` — name+chain based, not a real UUID),
+   * which the child mirrors back as
+   * `SolanaWalletService.connectedWalletUuid`. Deliberately re-resolves the
+   * REAL, in-frame adapter (via `getWallets()`) rather than reusing the
+   * serialized `walletStandardWallets[].adapter` object — that object only
+   * exposes the whitelisted sign/transaction methods for Comlink, not
+   * `.on`/`.off`, so it can't be used to attach a live listener. Forwards a
+   * plain `string | null` (never a `PublicKey`) to `callback`, a
+   * Comlink-proxied callback the child supplies. Throws when no wallet
+   * matches `walletId` (reported as a bridge error on the child side,
+   * mirroring `subscribeEip6963ProviderEvent`'s uuid-miss); returns
+   * `undefined` when the resolved adapter can't be observed.
+   */
+  subscribeSolanaWalletEvent: (
+    walletId: string,
+    callback: (address: string | null) => void
+  ) => (() => void) | undefined
 }
 
 export class BridgeParent {
@@ -154,6 +225,10 @@ export class BridgeParent {
     options: EndpointAddEventListenerOptions
   }> = []
   private destroyed = false
+  // Captured so subscribeEip6963ProviderEvent can await the one-shot discovery
+  // window before its uuid/rdns lookup, instead of racing an empty
+  // eip6963Wallets when a subscribe call arrives before discovery resolves.
+  private eip6963DiscoveryPromise: Promise<DetectedWallet[]> | null = null
 
   constructor(iframe: HTMLIFrameElement) {
     if (!iframe) {
@@ -176,6 +251,7 @@ export class BridgeParent {
     // while that's in flight — those paths are independent. The readiness
     // flags gate the child from reading a still-empty array.
     const eip6963Promise = this.discovereip6963Wallets()
+    this.eip6963DiscoveryPromise = eip6963Promise
     // Solana is synchronous, so run it inline (no benefit to a microtask hop)
     const walletStandardWallets = this.getSolanaWallets()
 
@@ -206,6 +282,215 @@ export class BridgeParent {
           this.parentAPI.tonWallets = this.getTonWallets(jsBridgeKeys)
           this.parentAPI.tonWalletsReady = true
         }
+      },
+
+      subscribeEip6963ProviderEvent: async (
+        uuid: string,
+        eventName: 'accountsChanged' | 'chainChanged' | 'disconnect',
+        callback: (payload?: unknown) => void,
+        rdns?: string
+      ): Promise<(() => void) | undefined> => {
+        // Discovery is one-shot with a fixed window (see
+        // discovereip6963Wallets) — a subscribe call can legitimately arrive
+        // before it resolves (e.g. immediately on page load during a session
+        // restore). Awaiting here means the lookup below always runs against
+        // the FINAL discovered list instead of racing a still-empty one. This
+        // is safe to await unconditionally: it resolves immediately once
+        // discovery has already completed. Comlink calls are already async
+        // over postMessage (the child already wraps this in
+        // `Promise.resolve()` — see BridgeChild.ts), so returning a Promise
+        // here changes nothing from the child's perspective.
+        await this.eip6963DiscoveryPromise
+        const wallets = this.parentAPI?.eip6963Wallets ?? []
+        // uuid is the primary match. It can genuinely diverge from what this
+        // parent discovered: each independent EIP-6963 injection context
+        // (top frame vs. this iframe) mints its own random uuid per spec, so
+        // the SAME physical wallet can be known under two different uuids —
+        // widening the discovery window (see the sibling plan this one
+        // follows) only narrows that race, it can't close it. rdns
+        // ("io.metamask"-style) is wallet-defined and stable across
+        // injection contexts, so it's a reliable fallback identity when the
+        // uuid the child captured doesn't match anything this parent saw.
+        const wallet =
+          wallets.find(w => w.uuid === uuid) ??
+          (rdns ? wallets.find(w => w.rdns === rdns) : undefined)
+        if (!wallet) {
+          // Neither the uuid nor (if supplied) the rdns matched anything —
+          // genuinely not discovered by this parent. Throwing — instead of
+          // returning undefined like the "found but not observable" branch
+          // below does — turns this into a reported bridge error on the
+          // child side (see BridgeChild.ts's
+          // window.__uwcSubscribeEip6963ProviderEvent) instead of a silent,
+          // undetectable no-op.
+          throw new Error(
+            `subscribeEip6963ProviderEvent: no wallet found for uuid "${uuid}"`
+          )
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const provider = wallet.provider as any
+        if (!provider || typeof provider.on !== 'function') return undefined
+        // `callback` here IS the Comlink proxy the child passed — registering
+        // it DIRECTLY as the provider's own event listener would make Comlink
+        // serialize EVERY argument the wallet's own dispatch calls it with.
+        // Some wallets' internal EventEmitter passes extra, non-EIP-1193
+        // arguments alongside the real payload (observed in production: a
+        // wallet's own internal accountsChanged handler function), and
+        // Comlink can't clone a function — throwing "DataCloneError" the
+        // moment the wallet actually fires the event, silently breaking
+        // delivery. A local (non-proxied, ordinary JS) wrapper that only
+        // forwards the first argument sidesteps this entirely — extra
+        // arguments are simply never looked at, the same way the direct
+        // (non-bridge) `EthereumWalletService.onLifecycleEvent` path already
+        // does by using a plain single-parameter handler.
+        const localListener = (payload?: unknown) => callback(payload)
+        provider.on(eventName, localListener)
+        // The teardown crosses back to the child as a Comlink return value —
+        // like TON's `listen()` above, an un-proxied function can't be
+        // structured-cloned over postMessage (Comlink throws
+        // "Unserializable return value" the moment the child tries to
+        // receive it), silently losing the child's ability to unsubscribe.
+        // The block body below is deliberate, not stylistic: an
+        // expression-bodied `() => provider.removeListener?.(...)` would
+        // implicitly return removeListener's OWN return value — by
+        // EventEmitter convention that's `this` (the whole provider), which
+        // is itself unserializable and reproduces the exact same failure one
+        // level down, the moment this teardown is actually invoked.
+        return Comlink.proxy(() => {
+          provider.removeListener?.(eventName, localListener)
+        })
+      },
+      subscribeTronProviderEvent: (
+        injectedId: string,
+        eventName: 'accountsChanged' | 'disconnect',
+        callback: (payload?: unknown) => void
+      ): (() => void) | undefined => {
+        const provider = this.resolveTronProviderByPath(injectedId)
+        if (!provider) {
+          // Same rationale as subscribeEip6963ProviderEvent above — surface
+          // a genuine "nothing at this path" miss as a reported bridge
+          // error instead of a silent no-op.
+          throw new Error(
+            `subscribeTronProviderEvent: no provider found at injectedId "${injectedId}"`
+          )
+        }
+        // Choose an EVENT-CAPABLE emitter. The provider resolved by
+        // `injectedId` (e.g. `window.tronLink`) carries `request`+`tronWeb` —
+        // enough for discovery + signing — but is NOT necessarily an event
+        // emitter. TronLink specifically injects a SEPARATE TIP-1193 provider
+        // at `window.tron` that is the one emitting `accountsChanged` /
+        // `disconnect`; `window.tronLink` has no `.on`, so binding there
+        // silently dropped every in-wallet account switch (MFS-778). Order:
+        //   1) the resolved provider itself (Trust / Bitget expose their own `.on`)
+        //   2) TronLink's TIP-1193 `window.tron` — but ONLY for the TronLink
+        //      subscription (see `resolveTronEventEmitter`). A wallet whose own
+        //      Tron provider lacks `.on` (e.g. OKX's `okxwallet.tronLink`) must
+        //      NOT inherit TronLink's `window.tron`, or its switches bind to the
+        //      wrong wallet and are dropped — it falls through to (3) instead.
+        //   3) the window `message` channel (below), which OKX actually uses.
+        const emitter =
+          typeof provider.on === 'function'
+            ? provider
+            : this.resolveTronEventEmitter(injectedId, provider)
+        if (emitter) {
+          // Same "don't register the raw Comlink proxy directly" requirement
+          // as subscribeEip6963ProviderEvent above.
+          const localListener = (payload?: unknown) => callback(payload)
+          emitter.on(eventName, localListener)
+          // Same block-body requirement as subscribeEip6963ProviderEvent above
+          // — discard removeListener's own (EventEmitter-convention `this`)
+          // return value rather than implicitly returning it.
+          return Comlink.proxy(() => {
+            emitter.removeListener?.(eventName, localListener)
+          })
+        }
+        //   3) Legacy TronLink builds expose neither `.on` surface: the wallet
+        //      broadcasts account/disconnect changes as `window` `message`
+        //      events instead. Last-resort, and window-global (not
+        //      wallet-scoped), so only reached when no emitter exists at all.
+        return Comlink.proxy(
+          this.subscribeTronWindowMessage(eventName, callback)
+        )
+      },
+      subscribeSolanaWalletEvent: (
+        walletId: string,
+        callback: (address: string | null) => void
+      ): (() => void) | undefined => {
+        const adapter = this.resolveSolanaAdapterForWalletEvent(walletId)
+        if (!adapter) {
+          // Same rationale as subscribeEip6963ProviderEvent's uuid miss —
+          // surface a genuine "nothing at this walletId" miss as a reported
+          // bridge error instead of a silent no-op.
+          throw new Error(
+            `subscribeSolanaWalletEvent: no wallet found for walletId "${walletId}"`
+          )
+        }
+        // PREFERRED — subscribe to the underlying wallet's wallet-standard
+        // `standard:events` `change` stream, which fires on EVERY account switch
+        // and carries the wallet's updated `accounts`. We must NOT derive switches
+        // from the adapter's own `connect`/`disconnect` here:
+        // `resolveSolanaAdapterForWalletEvent` returns a FRESH, never-connected
+        // `StandardWalletAdapter`, and that adapter only translates a `change` into
+        // `connect`/`disconnect` when it is already connected — so on the bridge an
+        // account-to-account switch emits NEITHER event and is silently dropped
+        // (only an eventual full de-auth trips `disconnect`). That is the Phantom
+        // multi-switch regression: several switches produce no telemetry and no
+        // session update, and only the final de-auth disconnects (MFS-778).
+        // Reading the wallet's `standard:events` directly captures every switch.
+        const standardWallet = (
+          adapter as unknown as { wallet?: StandardEventsCapableWallet }
+        ).wallet
+        const standardEvents = standardWallet?.features?.['standard:events']
+        if (standardWallet && typeof standardEvents?.on === 'function') {
+          // Forward the authoritative current active account as a plain base58
+          // string | null BEFORE crossing Comlink (the raw account object isn't
+          // structured-cloneable, and the child only needs the address). null =
+          // the switch de-authorized the dapp → the child maps it to [] (disconnect),
+          // a non-null address maps to [address] (switch), exactly as the legacy
+          // connect/disconnect path did.
+          const forwardActiveAccount = () => {
+            callback(standardWallet.accounts?.[0]?.address ?? null)
+          }
+          const off = standardEvents.on('change', properties => {
+            // React only to account-set changes; ignore pure chain/feature deltas.
+            if (properties && 'accounts' in properties) forwardActiveAccount()
+          })
+          // Block body (not an expression arrow): the wallet-standard unsubscribe
+          // returns its own value, which must not become this teardown's
+          // (unserializable) return across Comlink. Best-effort + idempotent.
+          return Comlink.proxy(() => {
+            try {
+              off?.()
+            } catch {
+              // Unsubscribe must never throw across the bridge.
+            }
+          })
+        }
+
+        // FALLBACK — a traditional (non-wallet-standard) adapter, e.g. the legacy
+        // Base Wallet, exposes only EventEmitter `connect`/`disconnect` and no
+        // `standard:events` stream. Its connected instance re-emits `connect` on a
+        // switch, so this path stays correct for it.
+        if (typeof adapter.on !== 'function') return undefined
+
+        // Reduce to a plain string | null BEFORE crossing Comlink — the raw
+        // PublicKey (or the adapter/emitter itself) must never be forwarded:
+        // it isn't structured-cloneable and the child only ever needs the
+        // base58 address.
+        const onConnect = (publicKey?: { toBase58?: () => string } | null) => {
+          callback(publicKey?.toBase58?.() ?? null)
+        }
+        const onDisconnect = () => callback(null)
+        adapter.on('connect', onConnect)
+        adapter.on('disconnect', onDisconnect)
+        // Block body — same requirement as subscribeEip6963ProviderEvent's
+        // teardown above: an expression-bodied `() => adapter.off(...)`
+        // would implicitly return `.off`'s own (EventEmitter-convention
+        // `this`) value, reproducing the unserializable-return-value failure
+        // one level down, the moment this teardown is actually invoked.
+        return Comlink.proxy(() => {
+          adapter.off('connect', onConnect)
+          adapter.off('disconnect', onDisconnect)
+        })
       }
     }
 
@@ -288,7 +573,16 @@ export class BridgeParent {
   private async discovereip6963Wallets(): Promise<DetectedWallet[]> {
     return new Promise(resolve => {
       const detectedWallets: DetectedWallet[] = []
-      const timeout = 100 // Wait 100ms for wallets to announce
+      // 300ms (not 100ms): a wallet extension racing other extensions to
+      // inject, or a slow page load, can announce after a 100ms window
+      // closes — this parent's discovery is one-shot with no retry, so a
+      // missed announcement is missed forever for this session. Widening
+      // the window doesn't make discovery bulletproof (no fixed window
+      // can be), but meaningfully reduces how often a real wallet gets
+      // missed here and pushed onto the CHILD's local-discovery fallback,
+      // which is where the uuid-mismatch bug this constant guards against
+      // originates.
+      const timeout = 300 // Wait 300ms for wallets to announce
 
       // Set up listener for wallet announcements
       const handleAnnouncement = (event: Event) => {
@@ -738,6 +1032,165 @@ export class BridgeParent {
     return provider['tronWeb'] != null && 'request' in provider
   }
 
+  /**
+   * Resolve the REAL (non-serialized) Solana adapter for `walletId` — the
+   * same id `getSolanaWallets()` publishes as `WalletStandardInfo.uuid` (see
+   * `generateWalletId`). Mirrors `getSolanaWallets()`'s wallet-standard +
+   * traditional-Base-Wallet resolution, but returns the adapter instance
+   * itself instead of the Comlink-serialized object literal, since only the
+   * real instance has `.on`/`.off` to subscribe to.
+   */
+  private resolveSolanaAdapterForWalletEvent(
+    walletId: string
+  ): StandardWalletAdapter | BaseWalletAdapter | undefined {
+    const { get } = getWallets()
+    const wallets = get()
+
+    for (const wallet of wallets) {
+      if (!this.isSolanaWallet(wallet)) continue
+      if (this.generateWalletId(wallet) !== walletId) continue
+      if (!isWalletAdapterCompatibleStandardWallet(wallet)) return undefined
+      return new StandardWalletAdapter({ wallet })
+    }
+
+    try {
+      const baseAdapter = new BaseWalletAdapter()
+      const baseWalletId = `${baseAdapter.name}-traditional`
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+      const isDetected =
+        baseAdapter.readyState === WalletReadyState.Installed ||
+        baseAdapter.readyState === WalletReadyState.Loadable
+      if (baseWalletId === walletId && isDetected) {
+        return baseAdapter
+      }
+    } catch {
+      // Base Wallet adapter failed to initialize — no traditional fallback.
+    }
+
+    return undefined
+  }
+
+  /** Resolve a nested window path (e.g. 'tokenpocket.tron' -> window.tokenpocket.tron). */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private resolveTronProviderByPath(injectedId: string): any {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return injectedId.split('.').reduce<any>(
+      (acc, part) => acc?.[part],
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      window as any
+    )
+  }
+
+  /**
+   * TronLink's account/disconnect events fire on its TIP-1193 provider
+   * (`window.tron`), NOT on the `window.tronLink` object the catalog
+   * `injectedId` resolves to (that one carries `request`+`tronWeb` but is not
+   * an event emitter). Returns TronLink's `window.tron` emitter, but ONLY when
+   * the subscription is for TronLink itself.
+   *
+   * `window.tron` belongs exclusively to TronLink. Other Tron wallets whose own
+   * provider happens to lack `.on` (confirmed for OKX's `okxwallet.tronLink`,
+   * which is not an event emitter and broadcasts account switches on the window
+   * `message` channel instead) MUST NOT inherit it — binding OKX's
+   * `accountsChanged` on TronLink's `window.tron` means OKX's switches fire on
+   * the wrong wallet's provider and are silently dropped. Gated on the
+   * subscription's identity so only the TronLink path uses this fallback; every
+   * other wallet falls through to `subscribeTronWindowMessage`.
+   */
+  private resolveTronEventEmitter(
+    injectedId: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    provider: any
+  ):
+    | {
+        on: (event: string, handler: (...args: unknown[]) => void) => void
+        removeListener?: (
+          event: string,
+          handler: (...args: unknown[]) => void
+        ) => void
+      }
+    | undefined {
+    if (typeof window === 'undefined') return undefined
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const win = window as any
+    const tip1193 = win.tron
+    if (
+      !tip1193 ||
+      typeof tip1193.on !== 'function' ||
+      !this.isTronProvider(tip1193)
+    ) {
+      return undefined
+    }
+    // Only TronLink may use its own `window.tron`. Identify the TronLink
+    // subscription by provider identity (the resolved provider IS `window.tron`
+    // / `window.tronLink`) or the canonical TronLink injectedId paths.
+    const isTronLinkSubscription =
+      provider === tip1193 ||
+      provider === win.tronLink ||
+      injectedId === 'tron' ||
+      injectedId === 'tronLink'
+    if (isTronLinkSubscription) {
+      return tip1193
+    }
+    return undefined
+  }
+
+  /**
+   * Last-resort account/disconnect subscription for TronLink builds that expose
+   * neither an EIP-1193 nor a TIP-1193 `.on`: the wallet broadcasts changes as
+   * `window` `message` events (`{ message: { action, data } }`). Maps the
+   * TronLink `action` to the requested UWC event and forwards a
+   * Comlink-cloneable payload (never the raw event). Returns a teardown.
+   *
+   * `message` is window-global (not wallet-scoped), so this is only reached
+   * when no `.on` emitter exists anywhere for this session.
+   */
+  private subscribeTronWindowMessage(
+    eventName: 'accountsChanged' | 'disconnect',
+    callback: (payload?: unknown) => void
+  ): () => void {
+    const handler = (event: MessageEvent) => {
+      // Runs in the client's TOP frame and the payload flows straight into the
+      // live session address, so only trust broadcasts from THIS window — the
+      // page context TronLink/OKX inject into. Without this, any same-origin
+      // sibling frame or `window.opener` could post `{ message: { action:
+      // 'setAccount' } }` and move the user's account. Mirrors the posture of
+      // `wrapWithSourceGuard` and `Comlink.expose(..., [iframeOrigin])`.
+      if (event.source !== window || event.origin !== window.location.origin) {
+        return
+      }
+      const message = (
+        event?.data as { message?: { action?: unknown; data?: unknown } }
+      )?.message
+      const action = message?.action
+      if (typeof action !== 'string') return
+      if (
+        eventName === 'accountsChanged' &&
+        (action === 'setAccount' || action === 'accountsChanged')
+      ) {
+        const data = message?.data as
+          | { address?: string }
+          | string
+          | string[]
+          | undefined
+        const address =
+          typeof data === 'string'
+            ? data
+            : Array.isArray(data)
+              ? data[0]
+              : data?.address
+        // Match the TIP-1193 `accountsChanged` shape (`string[]`) so the
+        // connector's normalization treats an absent address as a logout.
+        callback(address ? [address] : [])
+      } else if (eventName === 'disconnect' && action === 'disconnect') {
+        callback()
+      }
+    }
+    window.addEventListener('message', handler)
+    return () => window.removeEventListener('message', handler)
+  }
+
   private getTronWallets(injectedIds: string[]): TronWalletInfo[] {
     if (typeof window === 'undefined' || injectedIds.length === 0) {
       return []
@@ -747,13 +1200,7 @@ export class BridgeParent {
     const seen = new Set<string>()
 
     for (const injectedId of injectedIds) {
-      // Resolve nested window path (e.g. 'tokenpocket.tron' -> window.tokenpocket.tron)
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const provider = injectedId.split('.').reduce<any>(
-        (acc, part) => acc?.[part],
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        window as any
-      )
+      const provider = this.resolveTronProviderByPath(injectedId)
 
       // Check if it looks like a TronProvider (has tronWeb.trx)
       if (this.isTronProvider(provider) && !seen.has(injectedId)) {