@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/observability/lifecycle-bridge.test.ts

@@ -0,0 +1,398 @@
+import { describe, it, expect } from 'vitest'
+import type { WalletLifecycleEvent, Network } from '@meshconnect/uwc-types'
+import { EventManager } from '../managers/event-manager'
+import {
+  attachLifecycle,
+  MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT,
+  type LifecycleRouting
+} from './lifecycle-bridge'
+
+const routing: LifecycleRouting = {
+  connectionMode: 'injected',
+  walletId: 'metamask',
+  namespace: 'eip155'
+}
+
+const switchedTo = (id: string) =>
+  ({ network: { id } as unknown as Network }) as { network: Network }
+
+describe('attachLifecycle', () => {
+  it('maps lifecycle events to bus events with routing (no address)', () => {
+    const em = new EventManager()
+    const got: Record<string, unknown[]> = {}
+    for (const n of [
+      'walletAccountChanged',
+      'walletChainChanged',
+      'walletDisconnected',
+      'walletSessionExpired'
+    ] as const) {
+      em.on(n, d => (got[n] ??= []).push(d))
+    }
+
+    let emit!: (e: WalletLifecycleEvent) => void
+    attachLifecycle({
+      eventManager: em,
+      subscribe: l => {
+        emit = l
+        return () => {}
+      },
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      walletId: 'metamask',
+      namespace: 'eip155'
+    })
+
+    emit({ type: 'accountChanged' })
+    emit({ type: 'chainChanged', chainId: 'eip155:8453' })
+    emit({ type: 'disconnect' })
+    emit({ type: 'sessionExpired' })
+
+    expect(got.walletAccountChanged).toEqual([routing])
+    expect(got.walletChainChanged).toEqual([
+      { ...routing, chainId: 'eip155:8453' }
+    ])
+    expect(got.walletDisconnected).toEqual([routing])
+    expect(got.walletSessionExpired).toEqual([routing])
+  })
+
+  it('a throwing getRouting never escapes into the wallet emitter dispatch', () => {
+    // Wallet SDKs dispatch listeners unguarded (e.g. TonConnect's bare
+    // forEach) — a throw from our listener would abort delivery to the
+    // wallet's own later subscribers.
+    const em = new EventManager()
+    let emit!: (e: WalletLifecycleEvent) => void
+    attachLifecycle({
+      eventManager: em,
+      subscribe: l => {
+        emit = l
+        return () => {}
+      },
+      getRouting: () => {
+        throw new Error('poisoned routing')
+      },
+      connectionMode: 'injected',
+      walletId: 'metamask',
+      namespace: 'eip155'
+    })
+
+    expect(() => emit({ type: 'accountChanged' })).not.toThrow()
+  })
+
+  it('suppresses a chainChanged that echoes a UWC-initiated switch', () => {
+    let t = 1000
+    const em = new EventManager()
+    const seen: unknown[] = []
+    em.on('walletChainChanged', d => seen.push(d))
+
+    let emit!: (e: WalletLifecycleEvent) => void
+    attachLifecycle({
+      eventManager: em,
+      subscribe: l => {
+        emit = l
+        return () => {}
+      },
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155',
+      now: () => t
+    })
+
+    // UWC drives the switch → networkSwitched on the bus; the wallet's echo for
+    // the same chain inside the window is dropped.
+    em.emit('networkSwitched', switchedTo('eip155:8453'))
+    emit({ type: 'chainChanged', chainId: 'eip155:8453' })
+    expect(seen).toHaveLength(0)
+
+    // The same chainChanged past the echo window is a genuine wallet-side switch.
+    t = 1000 + 5000
+    emit({ type: 'chainChanged', chainId: 'eip155:8453' })
+    expect(seen).toHaveLength(1)
+  })
+
+  it('suppresses an echo that lands BEFORE networkSwitched (provider emits early)', () => {
+    // Some providers emit their own chainChanged BEFORE the switch request
+    // resolves — i.e. before UWC emits networkSwitched. The suppression window
+    // is therefore ALSO armed from the switch handoff start (awaitingWallet
+    // with operation switchNetwork), which always precedes the wallet call.
+    let t = 1000
+    const em = new EventManager()
+    const seen: unknown[] = []
+    em.on('walletChainChanged', d => seen.push(d))
+
+    let emit!: (e: WalletLifecycleEvent) => void
+    attachLifecycle({
+      eventManager: em,
+      subscribe: l => {
+        emit = l
+        return () => {}
+      },
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155',
+      now: () => t
+    })
+
+    em.emit('awaitingWallet', {
+      operation: 'switchNetwork',
+      connectionMode: 'injected',
+      walletId: 'metamask',
+      namespace: 'eip155',
+      chainId: 'eip155:8453',
+      handoffId: 'h-switch',
+      walletFlowType: 'browser_extension_flow',
+      platform: 'desktop'
+    })
+    // The wallet's early echo — no networkSwitched has fired yet.
+    emit({ type: 'chainChanged', chainId: 'eip155:8453' })
+    expect(seen).toHaveLength(0)
+
+    // A LATER user-initiated switch-back to the same chain must still surface.
+    t = 1500
+    emit({ type: 'chainChanged', chainId: 'eip155:8453' })
+    expect(seen).toHaveLength(1)
+  })
+
+  it('caps lifecycle emissions per attachment (a storming provider cannot drive unbounded egress)', () => {
+    // Every other telemetry sink added by this layer is bounded (relay / bridge /
+    // observer-error all cap at 100); a wallet looping chainChanged must not be
+    // the one unbounded path to the observer.
+    const em = new EventManager()
+    const seen: unknown[] = []
+    em.on('walletChainChanged', d => seen.push(d))
+    em.on('walletAccountChanged', d => seen.push(d))
+    const unavail: Array<{ reason?: string }> = []
+    em.on('lifecycleTelemetryUnavailable', d =>
+      unavail.push(d as { reason?: string })
+    )
+
+    let emit!: (e: WalletLifecycleEvent) => void
+    attachLifecycle({
+      eventManager: em,
+      subscribe: l => {
+        emit = l
+        return () => {}
+      },
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155'
+    })
+
+    for (let i = 0; i < MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT + 50; i++) {
+      emit({ type: 'chainChanged', chainId: `eip155:${i}` })
+    }
+    expect(seen).toHaveLength(MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT)
+
+    // Once capped, every lifecycle type stays silenced for this attachment…
+    emit({ type: 'accountChanged' })
+    expect(seen).toHaveLength(MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT)
+
+    // …but the trip itself is marked ONCE, so a dashboard can tell "provider
+    // went quiet" from "provider stormed and got capped".
+    expect(unavail).toHaveLength(1)
+    expect(unavail[0]?.reason).toBe('emission_cap')
+  })
+
+  it('seeds echo suppression from initialSwitch (the reattach-after-switch path)', () => {
+    // A cross-namespace switchNetwork re-attaches the subscription AFTER the
+    // switch completed — the fresh closure never saw that switch's bus events,
+    // so without a seed the new provider's echo would surface as wallet-initiated.
+    let t = 1000
+    const em = new EventManager()
+    const seen: unknown[] = []
+    em.on('walletChainChanged', d => seen.push(d))
+
+    let emit!: (e: WalletLifecycleEvent) => void
+    attachLifecycle({
+      eventManager: em,
+      subscribe: l => {
+        emit = l
+        return () => {}
+      },
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155',
+      initialSwitch: { chainId: 'eip155:8453', at: 1000 },
+      now: () => t
+    })
+
+    // The just-switched chain's echo is suppressed…
+    emit({ type: 'chainChanged', chainId: 'eip155:8453' })
+    expect(seen).toHaveLength(0)
+
+    // …and CONSUMED: a later same-chain change is genuine and surfaces.
+    t = 1500
+    emit({ type: 'chainChanged', chainId: 'eip155:8453' })
+    expect(seen).toHaveLength(1)
+  })
+
+  it('a connect handoff does not arm echo suppression', () => {
+    const em = new EventManager()
+    const seen: unknown[] = []
+    em.on('walletChainChanged', d => seen.push(d))
+
+    let emit!: (e: WalletLifecycleEvent) => void
+    attachLifecycle({
+      eventManager: em,
+      subscribe: l => {
+        emit = l
+        return () => {}
+      },
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155'
+    })
+
+    em.emit('awaitingWallet', {
+      operation: 'connect',
+      connectionMode: 'injected',
+      walletId: 'metamask',
+      namespace: 'eip155',
+      chainId: 'eip155:8453',
+      handoffId: 'h-connect',
+      walletFlowType: 'browser_extension_flow',
+      platform: 'desktop'
+    })
+    emit({ type: 'chainChanged', chainId: 'eip155:8453' })
+
+    expect(seen).toHaveLength(1)
+  })
+
+  it('teardown removes the awaitingWallet watcher too (no lingering bus listeners)', () => {
+    const em = new EventManager()
+    const baseline = em.getListenerCount()
+
+    const teardown = attachLifecycle({
+      eventManager: em,
+      subscribe: () => () => {},
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155'
+    })
+    expect(em.getListenerCount()).toBeGreaterThan(baseline)
+
+    teardown()
+    expect(em.getListenerCount()).toBe(baseline)
+  })
+
+  it('reports unsupported_namespace on the direct page when the connector has no lifecycle support', () => {
+    const em = new EventManager()
+    const unavail: unknown[] = []
+    em.on('lifecycleTelemetryUnavailable', d => unavail.push(d))
+
+    attachLifecycle({
+      eventManager: em,
+      subscribe: undefined,
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155',
+      walletId: 'metamask'
+    })
+
+    expect(unavail).toEqual([
+      {
+        reason: 'unsupported_namespace',
+        connectionMode: 'injected',
+        namespace: 'eip155',
+        walletId: 'metamask',
+        runtime: 'direct'
+      }
+    ])
+  })
+
+  it('reports bridge_subscription_unavailable in the iframe (bridge is why lifecycle is silent)', () => {
+    const em = new EventManager()
+    const unavail: Array<{ reason?: string; runtime?: string }> = []
+    em.on('lifecycleTelemetryUnavailable', d =>
+      unavail.push(d as { reason?: string; runtime?: string })
+    )
+
+    // No lifecycle surface AND running inside the Link iframe.
+    attachLifecycle({
+      eventManager: em,
+      subscribe: () => undefined,
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155',
+      runtime: 'iframe'
+    })
+
+    expect(unavail).toHaveLength(1)
+    expect(unavail[0]?.reason).toBe('bridge_subscription_unavailable')
+    expect(unavail[0]?.runtime).toBe('iframe')
+  })
+
+  it('emits unavailable (and does not leak the bus watchers) when subscribe returns undefined', () => {
+    const em = new EventManager()
+    const unavail: unknown[] = []
+    em.on('lifecycleTelemetryUnavailable', d => unavail.push(d))
+    const baseline = em.getListenerCount()
+
+    const teardown = attachLifecycle({
+      eventManager: em,
+      subscribe: () => undefined, // accepted the call but no observable surface
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155'
+    })
+
+    expect(unavail).toHaveLength(1)
+    // Every bus watcher (networkSwitched + awaitingWallet) is removed on this
+    // degraded path — nothing lingers for a session that can't be observed.
+    expect(em.getListenerCount()).toBe(baseline)
+    expect(() => teardown()).not.toThrow()
+  })
+
+  it('teardown removes the connector sub AND the networkSwitched watcher', () => {
+    const em = new EventManager()
+    let unsubbed = false
+    let emit!: (e: WalletLifecycleEvent) => void
+    const teardown = attachLifecycle({
+      eventManager: em,
+      subscribe: l => {
+        emit = l
+        return () => {
+          unsubbed = true
+        }
+      },
+      getRouting: () => routing,
+      connectionMode: 'injected',
+      namespace: 'eip155'
+    })
+
+    teardown()
+    expect(unsubbed).toBe(true)
+
+    // Watcher gone: a post-teardown networkSwitched no longer arms echo-suppression,
+    // so a chainChanged for that chain is NOT suppressed.
+    const seen: unknown[] = []
+    em.on('walletChainChanged', d => seen.push(d))
+    em.emit('networkSwitched', switchedTo('eip155:1'))
+    emit({ type: 'chainChanged', chainId: 'eip155:1' })
+    expect(seen).toHaveLength(1)
+  })
+
+  it('degrades to unavailable (never throws) when subscribe itself throws', () => {
+    // A connector whose subscribe throws — e.g. a provider whose `.on` rejects an
+    // un-proxied handler across the iframe bridge — must NOT break the connect
+    // path; it degrades to lifecycleTelemetryUnavailable.
+    const em = new EventManager()
+    const unavail: unknown[] = []
+    em.on('lifecycleTelemetryUnavailable', d => unavail.push(d))
+
+    let teardown!: () => void
+    expect(() => {
+      teardown = attachLifecycle({
+        eventManager: em,
+        subscribe: () => {
+          throw new Error('handler could not be cloned over the bridge')
+        },
+        getRouting: () => routing,
+        connectionMode: 'injected',
+        namespace: 'eip155'
+      })
+    }).not.toThrow()
+
+    expect(unavail).toHaveLength(1)
+    expect(() => teardown()).not.toThrow()
+  })
+})

package/src/observability/lifecycle-bridge.ts

@@ -0,0 +1,216 @@
+import type {
+  WalletLifecycleEvent,
+  ConnectionMode,
+  Namespace,
+  NetworkId,
+  LifecycleUnavailableReason
+} from '@meshconnect/uwc-types'
+import type { EventManager } from '../managers/event-manager'
+
+/** Routing facets stamped on every lifecycle event. No address. */
+export interface LifecycleRouting {
+  connectionMode: ConnectionMode
+  walletId?: string | undefined
+  namespace?: Namespace | undefined
+}
+
+/**
+ * Hard ceiling on lifecycle emissions per attachment. Every other telemetry
+ * sink this layer added is bounded (relay / bridge / observer-error dedup sets
+ * cap at 100); a provider looping `chainChanged`/`accountsChanged` must not be
+ * the one unbounded path to the observer. A legitimate session stays far below
+ * this; a storming provider goes silent instead of driving egress cost.
+ */
+export const MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT = 100
+
+export interface AttachLifecycleOptions {
+  eventManager: EventManager
+  /**
+   * The active connector's `onLifecycleEvent` (already bound). `undefined` when the
+   * connector can't observe lifecycle at all; the value it returns is `undefined`
+   * when THIS session can't be observed (e.g. no live `.on`). Either way the
+   * bridge emits `lifecycleTelemetryUnavailable` and becomes a no-op.
+   */
+  subscribe:
+    | ((l: (e: WalletLifecycleEvent) => void) => (() => void) | undefined)
+    | undefined
+  /** Resolved per-event so a mid-session account/chain change is reflected. */
+  getRouting: () => LifecycleRouting
+  connectionMode: ConnectionMode
+  namespace?: Namespace | undefined
+  walletId?: string | undefined
+  /** Direct page vs production iframe — stamped on `lifecycleTelemetryUnavailable`. */
+  runtime?: 'direct' | 'iframe'
+  /**
+   * Window (ms) within which a wallet `chainChanged` is treated as the echo of a
+   * UWC-initiated `switchNetwork` and suppressed. Default 3000.
+   */
+  echoWindowMs?: number
+  /**
+   * Seed for echo suppression when (re)attaching right AFTER a UWC-initiated
+   * switch completed (the cross-namespace reattach path): the fresh closure
+   * never saw that switch's `awaitingWallet`/`networkSwitched`, so the new
+   * provider's echo would otherwise surface as wallet-initiated. Same one-shot
+   * consume semantics as a bus-armed switch.
+   */
+  initialSwitch?: { chainId: NetworkId; at: number } | undefined
+  now?: () => number
+}
+
+/**
+ * Bridge a connector's PII-safe `WalletLifecycleEvent` stream onto the event bus
+ * as `walletAccountChanged` / `walletChainChanged` / `walletDisconnected` /
+ * `walletSessionExpired`.
+ *
+ * Two correctness concerns are handled here:
+ *  - **Echo suppression.** When UWC drives a `switchNetwork`, the wallet emits its
+ *    own `chainChanged` for the same chain — that's already captured by UWC's
+ *    `networkSwitched` / the switch handoff, so re-emitting it as a wallet-
+ *    initiated `walletChainChanged` would double-count. We watch the bus for
+ *    `networkSwitched` and drop a matching `chainChanged` inside `echoWindowMs`.
+ *  - **Availability is signal.** If the connector can't observe lifecycle, we emit
+ *    `lifecycleTelemetryUnavailable` ONCE so a dashboard can tell "silent" from
+ *    "unwired".
+ *
+ * @returns a teardown that removes the connector subscription AND the bus watcher.
+ */
+export function attachLifecycle(opts: AttachLifecycleOptions): () => void {
+  const { eventManager, subscribe, getRouting } = opts
+  const runtime = opts.runtime ?? 'direct'
+  const now = opts.now ?? Date.now
+  const echoWindowMs = opts.echoWindowMs ?? 3000
+
+  const emitUnavailable = (reason: LifecycleUnavailableReason) =>
+    eventManager.emit('lifecycleTelemetryUnavailable', {
+      reason,
+      connectionMode: opts.connectionMode,
+      namespace: opts.namespace,
+      walletId: opts.walletId,
+      runtime
+    })
+
+  if (!subscribe) {
+    // In the production iframe the injected subscription is deliberately not
+    // attempted (the provider is a Comlink proxy) — the BRIDGE, not the connector,
+    // is why lifecycle is unobservable. On the direct page, a connector with no
+    // `onLifecycleEvent` simply has no lifecycle support for this namespace yet.
+    emitUnavailable(
+      runtime === 'iframe'
+        ? 'bridge_subscription_unavailable'
+        : 'unsupported_namespace'
+    )
+    return () => {}
+  }
+
+  // Record UWC-initiated switches so the wallet's chainChanged echo can be
+  // dropped. Armed from BOTH signals: `awaitingWallet` (operation switchNetwork)
+  // arms at the handoff START, because some providers emit their chainChanged
+  // BEFORE the switch request resolves — i.e. before `networkSwitched` exists —
+  // and `networkSwitched` re-arms at completion for the late-echo case. The
+  // re-arm means one extra suppression window can follow an early echo; the
+  // only event it could swallow is a sub-window user re-switch to the chain
+  // that just became active — accepted over double-counting every early echo.
+  let lastSwitch: { chainId: NetworkId; at: number } | undefined =
+    opts.initialSwitch
+  const offAwaiting = eventManager.on('awaitingWallet', data => {
+    if (data.operation === 'switchNetwork' && data.chainId !== undefined) {
+      lastSwitch = { chainId: data.chainId, at: now() }
+    }
+  })
+  const offSwitched = eventManager.on('networkSwitched', data => {
+    lastSwitch = { chainId: data.network.id, at: now() }
+  })
+  const detachBusWatchers = () => {
+    offAwaiting()
+    offSwitched()
+  }
+
+  // Defense-in-depth: a connector whose subscribe THROWS (e.g. a provider whose
+  // `.on` rejects an un-proxied handler across the iframe bridge) must degrade to
+  // "unavailable", never break the connect path that called us.
+  let unsub: (() => void) | undefined
+  // Emission budget for THIS attachment — suppressed echoes don't spend it.
+  let emitted = 0
+  let capNotified = false
+  try {
+    unsub = subscribe(e => {
+      // The whole body is guarded: wallet SDKs dispatch their listeners
+      // unguarded (e.g. TonConnect's bare `forEach`), so a throw here — from
+      // `getRouting()` or any future edit — would abort delivery to the
+      // wallet's OWN later subscribers, including one resolving a pending
+      // connect. Telemetry must never do that.
+      try {
+        if (emitted >= MAX_LIFECYCLE_EVENTS_PER_ATTACHMENT) {
+          // Mark the trip ONCE — a silent cap would be indistinguishable from a
+          // provider that simply went quiet.
+          if (!capNotified) {
+            capNotified = true
+            emitUnavailable('emission_cap')
+          }
+          return
+        }
+        const routing = getRouting()
+        switch (e.type) {
+          case 'accountChanged':
+            emitted++
+            eventManager.emit('walletAccountChanged', routing)
+            return
+          case 'chainChanged': {
+            const isEcho =
+              !!lastSwitch &&
+              e.chainId !== undefined &&
+              lastSwitch.chainId === e.chainId &&
+              now() - lastSwitch.at <= echoWindowMs
+            if (isEcho) {
+              // Consume the echo: a UWC switch produces exactly one wallet echo, so
+              // a LATER chainChanged to the same chain inside the window is a genuine
+              // user-initiated switch-back and must not be suppressed.
+              lastSwitch = undefined
+              return
+            }
+            emitted++
+            eventManager.emit('walletChainChanged', {
+              ...routing,
+              ...(e.chainId !== undefined ? { chainId: e.chainId } : {})
+            })
+            return
+          }
+          case 'disconnect':
+            emitted++
+            eventManager.emit('walletDisconnected', routing)
+            return
+          case 'sessionExpired':
+            emitted++
+            eventManager.emit('walletSessionExpired', routing)
+            return
+        }
+      } catch {
+        // Swallowed: better to drop one lifecycle record than to break the
+        // wallet's event dispatch.
+      }
+    })
+  } catch {
+    unsub = undefined
+  }
+
+  // The connector accepted the subscribe call but this session has no observable
+  // surface (returned undefined) or threw — treat as "unavailable" and don't
+  // leave the bus watchers attached.
+  if (!unsub) {
+    detachBusWatchers()
+    // `onLifecycleEvent` ran but exposed no live subscription surface for this
+    // session (returned undefined or threw). Over the bridge, that absence is the
+    // bridge's doing, not the provider's.
+    emitUnavailable(
+      runtime === 'iframe'
+        ? 'bridge_subscription_unavailable'
+        : 'provider_subscription_unavailable'
+    )
+    return () => {}
+  }
+
+  return () => {
+    detachBusWatchers()
+    unsub()
+  }
+}