@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/utils/resolve-session-provider.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest'
+import type { Session, WalletMetadata } from '@meshconnect/uwc-types'
+import { resolveSessionProvider } from './resolve-session-provider'
+
+const extensionProvider = { kind: 'extension' }
+const integratedProvider = { kind: 'integrated' }
+const walletConnectProvider = { kind: 'walletConnect' }
+
+const wallet = {
+  id: 'metamask',
+  name: 'MetaMask',
+  extensionInjectedProvider: extensionProvider,
+  integratedBrowserInjectedProvider: integratedProvider,
+  walletConnectProvider
+} as unknown as WalletMetadata
+
+const session = (
+  connectionMode: Session['connectionMode'],
+  activeWallet: WalletMetadata | null = wallet
+) => ({ connectionMode, activeWallet }) as Session
+
+describe('resolveSessionProvider', () => {
+  it('resolves the extension provider for injected outside the integrated browser', () => {
+    expect(resolveSessionProvider(session('injected'), false)).toBe(
+      extensionProvider
+    )
+  })
+
+  it('resolves the integrated-browser provider for injected inside it', () => {
+    expect(resolveSessionProvider(session('injected'), true)).toBe(
+      integratedProvider
+    )
+  })
+
+  it('resolves the walletConnect provider for walletConnect', () => {
+    expect(resolveSessionProvider(session('walletConnect'), false)).toBe(
+      walletConnectProvider
+    )
+  })
+
+  it('yields undefined for tonConnect — the connector resolves its own provider', () => {
+    expect(resolveSessionProvider(session('tonConnect'), false)).toBeUndefined()
+  })
+
+  it('throws when the resolved provider is missing (configuration failure)', () => {
+    const bare = { id: 'metamask', name: 'MetaMask' } as WalletMetadata
+    expect(() =>
+      resolveSessionProvider(session('injected', bare), false)
+    ).toThrow('No provider available for the active wallet')
+    expect(() =>
+      resolveSessionProvider(session('walletConnect', bare), false)
+    ).toThrow('No provider available for the active wallet')
+  })
+})

package/src/utils/resolve-session-provider.ts

@@ -0,0 +1,25 @@
+import type { Session, SupportedProvider } from '@meshconnect/uwc-types'
+
+/**
+ * Resolve the active session's provider for a wallet-boundary op. This is
+ * validation, not wallet work — callers run it BEFORE `instrumentHandoff` so a
+ * missing provider (a configuration failure) never enters the handoff funnel.
+ * `tonConnect` resolves its provider inside the connector and legitimately
+ * yields undefined here.
+ */
+export function resolveSessionProvider(
+  session: Session,
+  usingIntegratedBrowser: boolean
+): SupportedProvider | undefined {
+  if (session.connectionMode === 'tonConnect') return undefined
+  const provider =
+    session.connectionMode === 'injected'
+      ? usingIntegratedBrowser
+        ? session.activeWallet?.integratedBrowserInjectedProvider
+        : session.activeWallet?.extensionInjectedProvider
+      : session.activeWallet?.walletConnectProvider
+  if (!provider) {
+    throw new Error('No provider available for the active wallet')
+  }
+  return provider
+}

package/src/utils/to-wallet-error.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect } from 'vitest'
+import {
+  WalletConnectorError,
+  NoCommonNetworkError
+} from '@meshconnect/uwc-types'
+import {
+  classifyError,
+  isAbortError,
+  isUserRejection,
+  toWalletError
+} from './to-wallet-error'
+
+describe('classifyError', () => {
+  it('classifies an explicit user rejection (EIP-1193 4001)', () => {
+    expect(classifyError({ code: 4001, message: 'User rejected' })).toEqual({
+      errorCode: '4001',
+      failureKind: 'user_rejected',
+      source: 'provider'
+    })
+  })
+
+  it('classifies a WalletConnectorError{rejected} as user_rejected/connector', () => {
+    const err = new WalletConnectorError({ type: 'rejected', message: 'no' })
+    expect(classifyError(err)).toEqual({
+      failureKind: 'user_rejected',
+      source: 'connector'
+    })
+  })
+
+  it('classifies NoCommonNetworkError as no_common_network/connector', () => {
+    // Delta A: the #1 prod connection failure gets its own kind. It is a
+    // WalletConnectorError subclass, so source is 'connector'; it has no numeric
+    // code, so errorCode is omitted.
+    const err = new NoCommonNetworkError(['eip155:1'], ['solana:101'])
+    expect(classifyError(err)).toEqual({
+      failureKind: 'no_common_network',
+      source: 'connector'
+    })
+  })
+
+  it('classifies -32002 (request already pending) as provider_error', () => {
+    // Delta B: the double-fire race. A provider-level error, not a user reject.
+    expect(classifyError({ code: -32002, message: 'already pending' })).toEqual(
+      {
+        errorCode: '-32002',
+        failureKind: 'provider_error',
+        source: 'provider'
+      }
+    )
+  })
+
+  it('classifies an expired WalletConnectorError', () => {
+    const err = new WalletConnectorError({ type: 'expired', message: 'gone' })
+    expect(classifyError(err)).toEqual({
+      failureKind: 'expired',
+      source: 'connector'
+    })
+  })
+
+  it('maps known EIP-1193 codes to coarse kinds', () => {
+    expect(classifyError({ code: 4200 }).failureKind).toBe('unsupported_method')
+    expect(classifyError({ code: -32601 }).failureKind).toBe(
+      'unsupported_method'
+    )
+    expect(classifyError({ code: -32602 }).failureKind).toBe('invalid_params')
+    expect(classifyError({ code: 4900 }).failureKind).toBe('network_error')
+    expect(classifyError({ code: 4901 }).failureKind).toBe('network_error')
+  })
+
+  it('falls back to unknown/unknown for a plain Error (no reliable signal)', () => {
+    // RELIABLE-ONLY: a plain Error carries no code and is not a typed connector
+    // error, so we never guess a kind from its message.
+    expect(classifyError(new Error('encoding overruns Uint8Array'))).toEqual({
+      failureKind: 'unknown',
+      source: 'unknown'
+    })
+  })
+
+  it('stringifies a string code without inventing a kind', () => {
+    expect(classifyError({ code: 'SERVER_ERROR' })).toEqual({
+      errorCode: 'SERVER_ERROR',
+      failureKind: 'unknown',
+      source: 'unknown'
+    })
+  })
+
+  it('scrubs a string error code (wallet-controlled free-form egress slot)', () => {
+    // A wallet can throw `{ code: '<anything>' }` — errorCode lands verbatim in
+    // walletRejected / walletFailed / error telemetry, so it must pass the same
+    // scrubber as error.message.
+    const addr = '0x' + 'a'.repeat(40)
+    const out = classifyError({ code: `denied for ${addr}` })
+    expect(out.errorCode).toBeDefined()
+    expect(out.errorCode).not.toContain(addr)
+    expect(out.errorCode).toContain('[redacted-hex]')
+  })
+
+  it('caps an over-long string error code', () => {
+    // '#' matches no scrub pattern, so this exercises the length cap itself.
+    const out = classifyError({ code: '#'.repeat(300) })
+    expect(out.errorCode).toBe('#'.repeat(64))
+  })
+
+  it('keeps known short string codes verbatim (ACTION_REJECTED)', () => {
+    expect(classifyError({ code: 'ACTION_REJECTED' })).toEqual({
+      errorCode: 'ACTION_REJECTED',
+      failureKind: 'user_rejected',
+      source: 'unknown'
+    })
+  })
+})
+
+describe('isUserRejection', () => {
+  it('is true for 4001 and ACTION_REJECTED and WalletConnectorError{rejected}', () => {
+    expect(isUserRejection({ code: 4001 })).toBe(true)
+    expect(isUserRejection({ code: 'ACTION_REJECTED' })).toBe(true)
+    expect(
+      isUserRejection(
+        new WalletConnectorError({ type: 'rejected', message: '' })
+      )
+    ).toBe(true)
+  })
+
+  it('is false for a NoCommonNetworkError (not a user action)', () => {
+    expect(isUserRejection(new NoCommonNetworkError([], []))).toBe(false)
+  })
+})
+
+describe('toWalletError', () => {
+  it('preserves the type of a NoCommonNetworkError (unknown)', () => {
+    const err = new NoCommonNetworkError(['eip155:1'], ['solana:101'])
+    expect(toWalletError(err)).toEqual({
+      type: 'unknown',
+      message:
+        'No common supported network found between wallet and configured networks'
+    })
+  })
+
+  it('bounds an over-long non-connector message (shared safeErrorMessage cap)', () => {
+    const err = new Error('x'.repeat(10_000))
+    expect(toWalletError(err).message).toHaveLength(500)
+  })
+})
+
+describe('poisoned error objects (throwing getters)', () => {
+  // These helpers run inside telemetry catch blocks — a getter that throws
+  // must never replace the real rejection with its own error.
+  const poisoned = () => {
+    const evil = new Error('real message')
+    for (const prop of ['message', 'code', 'name'] as const) {
+      Object.defineProperty(evil, prop, {
+        get() {
+          throw new Error(`poisoned ${prop}`)
+        }
+      })
+    }
+    return evil
+  }
+
+  it('toWalletError falls back instead of throwing', () => {
+    expect(toWalletError(poisoned())).toEqual({
+      type: 'unknown',
+      message: 'Unreadable error object'
+    })
+  })
+
+  it('isUserRejection returns false instead of throwing', () => {
+    expect(isUserRejection(poisoned())).toBe(false)
+  })
+
+  it('classifyError returns unknown/unknown instead of throwing', () => {
+    expect(classifyError(poisoned())).toEqual({
+      failureKind: 'unknown',
+      source: 'unknown'
+    })
+  })
+
+  it('isAbortError returns false instead of throwing', () => {
+    expect(isAbortError(poisoned())).toBe(false)
+  })
+})

package/src/utils/to-wallet-error.ts

@@ -0,0 +1,152 @@
+import {
+  WalletConnectorError,
+  NoCommonNetworkError,
+  safeErrorMessage,
+  type WalletError,
+  type FailureKind,
+  type ErrorSource
+} from '@meshconnect/uwc-types'
+import { scrubMessage } from '../observability/scrub'
+
+/**
+ * Cap for STRING error codes. A wallet controls `error.code`, so an unbounded
+ * string here is a free-form slot on the telemetry egress path. The longest
+ * legitimate enum-like code in the wild (ethers') is ~23 chars — 64 keeps every
+ * real code intact while bounding abuse.
+ */
+const MAX_ERROR_CODE_LENGTH = 64
+
+/**
+ * Normalize any thrown value into the PII-light `WalletError` shape.
+ *
+ * Every helper in this file guards its property reads: they run inside the
+ * telemetry catch blocks, where a poisoned getter (`code`/`message`/`toString`
+ * that throws) would otherwise REPLACE the real rejection with its own error.
+ */
+export function toWalletError(error: unknown): WalletError {
+  try {
+    if (error instanceof WalletConnectorError) {
+      return { type: error.type, message: error.message }
+    }
+    return { type: 'unknown', message: safeErrorMessage(error) }
+  } catch {
+    return { type: 'unknown', message: 'Unreadable error object' }
+  }
+}
+
+/**
+ * Whether a thrown value is an explicit user rejection. Connectors usually wrap
+ * these as `WalletConnectorError{type:'rejected'}`, but a raw EIP-1193 reject
+ * (code `4001`) or ethers' `ACTION_REJECTED` can also reach the façade.
+ */
+export function isUserRejection(error: unknown): boolean {
+  try {
+    if (error instanceof WalletConnectorError) return error.type === 'rejected'
+    const code = (error as { code?: unknown } | null | undefined)?.code
+    return code === 4001 || code === 'ACTION_REJECTED'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Classify a thrown wallet error into stable telemetry facets. RELIABLE-ONLY:
+ * every branch keys off a structural signal (a typed `WalletConnectorError`, an
+ * explicit user rejection, or a known EIP-1193 numeric code). Anything we can't
+ * place from that evidence stays `unknown` — we never infer a kind/source from a
+ * free-form message, which would be a guess and would also risk leaking content
+ * into a structured field.
+ */
+export function classifyError(error: unknown): {
+  errorCode?: string
+  failureKind: FailureKind
+  source: ErrorSource
+} {
+  try {
+    return classifyErrorUnguarded(error)
+  } catch {
+    return { failureKind: 'unknown', source: 'unknown' }
+  }
+}
+
+function classifyErrorUnguarded(error: unknown): {
+  errorCode?: string
+  failureKind: FailureKind
+  source: ErrorSource
+} {
+  const code = (error as { code?: unknown } | null | undefined)?.code
+  const hasNumericCode = typeof code === 'number'
+
+  // Numeric codes pass through; STRING codes are wallet-controlled free-form
+  // data headed for structured telemetry fields, so they get the same scrubber
+  // as error.message plus a length cap. Known enum-likes ('ACTION_REJECTED')
+  // are short and pattern-free — they pass unchanged.
+  const errorCode =
+    typeof code === 'number'
+      ? String(code)
+      : typeof code === 'string'
+        ? scrubMessage(code).slice(0, MAX_ERROR_CODE_LENGTH)
+        : undefined
+
+  const source: ErrorSource =
+    error instanceof WalletConnectorError
+      ? 'connector'
+      : hasNumericCode
+        ? 'provider'
+        : 'unknown'
+
+  let failureKind: FailureKind = 'unknown'
+  if (isUserRejection(error)) {
+    failureKind = 'user_rejected'
+  } else if (error instanceof NoCommonNetworkError) {
+    // The wallet and configured networks don't overlap — the #1 prod connection
+    // failure. Carries its own CAIP-2 id lists; the caller forwards them.
+    failureKind = 'no_common_network'
+  } else if (
+    error instanceof WalletConnectorError &&
+    error.type === 'expired'
+  ) {
+    failureKind = 'expired'
+  } else if (hasNumericCode) {
+    switch (code) {
+      case 4200:
+      case -32601:
+        failureKind = 'unsupported_method'
+        break
+      case -32602:
+        failureKind = 'invalid_params'
+        break
+      case 4900:
+      case 4901:
+        failureKind = 'network_error'
+        break
+      // -32002 = "resource unavailable": a connect/permission request is already
+      // pending for this origin. The double-fire race seen in prod (a second
+      // connect while one is open) — a provider-level error, not a user reject.
+      case -32002:
+        failureKind = 'provider_error'
+        break
+    }
+  }
+
+  return errorCode === undefined
+    ? { failureKind, source }
+    : { errorCode, failureKind, source }
+}
+
+/**
+ * Whether a thrown value is an intentional cancellation (AbortSignal / fetch
+ * abort). Matched by `name` rather than `instanceof Error` because a real abort is
+ * a `DOMException`, which is not an `Error` subclass in every runtime.
+ */
+export function isAbortError(error: unknown): boolean {
+  try {
+    return (
+      typeof error === 'object' &&
+      error !== null &&
+      (error as { name?: unknown }).name === 'AbortError'
+    )
+  } catch {
+    return false
+  }
+}

package/src/utils/validate-wallet-session.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from 'vitest'
+import type {
+  ConnectionMode,
+  Connector,
+  Session,
+  WalletMetadata
+} from '@meshconnect/uwc-types'
+import { SessionManager } from '../managers/session-manager'
+import {
+  validateWalletSession,
+  getSessionConnector
+} from './validate-wallet-session'
+
+const wallet = { id: 'metamask', name: 'MetaMask' } as WalletMetadata
+
+const managerWith = (session: Partial<Session>) => {
+  const manager = new SessionManager()
+  manager.updateSession(session)
+  return manager
+}
+
+describe('validateWalletSession', () => {
+  it('returns the session when all guards pass', () => {
+    const manager = managerWith({
+      connectionMode: 'injected',
+      activeWallet: wallet,
+      activeAddress: '0x123'
+    })
+    const session = validateWalletSession(manager, { requireAddress: true })
+    expect(session.activeWallet).toBe(wallet)
+  })
+
+  it('throws the public-API messages in guard order', () => {
+    expect(() =>
+      validateWalletSession(new SessionManager(), { requireAddress: true })
+    ).toThrow('No active wallet')
+    expect(() =>
+      validateWalletSession(managerWith({ activeWallet: wallet }), {
+        requireAddress: true
+      })
+    ).toThrow('No active connection')
+    expect(() =>
+      validateWalletSession(
+        managerWith({ activeWallet: wallet, connectionMode: 'injected' }),
+        { requireAddress: true }
+      )
+    ).toThrow('No active wallet address')
+  })
+
+  it('skips the address guard when requireAddress is false (Solana bytes path)', () => {
+    const manager = managerWith({
+      connectionMode: 'injected',
+      activeWallet: wallet
+    })
+    expect(
+      validateWalletSession(manager, { requireAddress: false }).connectionMode
+    ).toBe('injected')
+  })
+})
+
+describe('getSessionConnector', () => {
+  const session = { connectionMode: 'injected' } as Session
+
+  it('returns the connector registered for the session mode', () => {
+    const connector = { connect: vi.fn() } as unknown as Connector
+    const connectors = new Map<ConnectionMode, Connector>([
+      ['injected', connector]
+    ])
+    expect(getSessionConnector(connectors, session)).toBe(connector)
+  })
+
+  it('throws the public-API message when no connector is registered', () => {
+    expect(() => getSessionConnector(new Map(), session)).toThrow(
+      'No connector found for connection mode: injected'
+    )
+  })
+})

package/src/utils/validate-wallet-session.ts

@@ -0,0 +1,40 @@
+import type { ConnectionMode, Connector, Session } from '@meshconnect/uwc-types'
+import type { SessionManager } from '../managers/session-manager'
+
+/**
+ * Session guards shared by the signature/transaction services — the thrown
+ * messages are part of the public API and must stay stable. Runs BEFORE
+ * `instrumentHandoff` so a pre-wallet failure never enters the handoff funnel.
+ * The Solana bytes path deliberately skips the address guard
+ * (`requireAddress: false`) — it signs caller-supplied bytes.
+ */
+export function validateWalletSession(
+  sessionManager: SessionManager,
+  options: { requireAddress: boolean }
+): Session {
+  const session = sessionManager.getSession()
+  if (!session.activeWallet) {
+    throw new Error('No active wallet')
+  }
+  if (!session.connectionMode) {
+    throw new Error('No active connection')
+  }
+  if (options.requireAddress && !session.activeAddress) {
+    throw new Error('No active wallet address')
+  }
+  return session
+}
+
+/** Resolve the active session's connector — validation, same funnel rule. */
+export function getSessionConnector(
+  connectors: Map<ConnectionMode, Connector>,
+  session: Session
+): Connector {
+  const connector = connectors.get(session.connectionMode!)
+  if (!connector) {
+    throw new Error(
+      `No connector found for connection mode: ${session.connectionMode}`
+    )
+  }
+  return connector
+}

package/src/version.test.ts

@@ -0,0 +1,11 @@
+import { describe, it, expect } from 'vitest'
+import { UWC_CORE_VERSION } from './version'
+import pkg from '../package.json'
+
+describe('UWC_CORE_VERSION', () => {
+  it('matches package.json (stale? run: node scripts/generate-version.mjs)', () => {
+    // The constant is generated from package.json at build / version-packages
+    // time; this guard catches a manual bump that skipped regeneration.
+    expect(UWC_CORE_VERSION).toBe(pkg.version)
+  })
+})

package/src/version.ts

@@ -0,0 +1,2 @@
+// Generated from package.json by scripts/generate-version.mjs — do not edit.
+export const UWC_CORE_VERSION = '1.1.0'