@meshconnect/uwc-core 1.0.1-snapshot.c7e65ce → 1.0.2

package/src/observability/scrub.test.ts

@@ -1,109 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { scrubValue, scrubMessage, scrubArgs } from './scrub'
-
-describe('scrub', () => {
-  it('redacts sensitive object keys (substring match, case-insensitive)', () => {
-    const out = scrubValue({
-      walletPrivateKey: '0xabc',
-      authToken: 'jwt',
-      'x-api-key': 'k',
-      mnemonic: 'a b c',
-      signature: '0xsig',
-      message: 'sign me',
-      chainId: 'eip155:1'
-    }) as Record<string, unknown>
-    expect(out.walletPrivateKey).toBe('[Redacted]')
-    expect(out.authToken).toBe('[Redacted]')
-    expect(out['x-api-key']).toBe('[Redacted]')
-    expect(out.mnemonic).toBe('[Redacted]')
-    expect(out.signature).toBe('[Redacted]')
-    expect(out.message).toBe('[Redacted]')
-    // Non-sensitive keys pass through.
-    expect(out.chainId).toBe('eip155:1')
-  })
-
-  it('redacts secrets embedded in free-form strings (hex blobs, k/v params, bearer)', () => {
-    // EVM address (40 nibbles) and a longer signature/key blob.
-    expect(
-      scrubMessage(
-        'insufficient funds for 0x1234567890abcdef1234567890abcdef12345678'
-      )
-    ).toBe('insufficient funds for 0x[redacted-hex]')
-    expect(
-      scrubMessage('relay https://r.io/?token=abc123secret&chain=1 failed')
-    ).toContain('token=[redacted]')
-    expect(scrubMessage('Authorization: Bearer eyJabc.def-ghi')).toContain(
-      'Bearer [redacted]'
-    )
-  })
-
-  it('redacts embedded secrets inside object string values too', () => {
-    const out = scrubValue({
-      note: 'sent to 0xabcdefabcdefabcdefabcdefabcdefabcdefabcd'
-    }) as Record<string, unknown>
-    expect(out.note).toBe('sent to 0x[redacted-hex]')
-  })
-
-  it('caps long strings', () => {
-    const long = 'x'.repeat(600)
-    const out = scrubMessage(long)
-    expect(out.length).toBeLessThan(600)
-    expect(out.endsWith('…[truncated]')).toBe(true)
-  })
-
-  it('redacts a hex blob before the length cap can slice it (no surviving tail)', () => {
-    // The secret must be redacted whole BEFORE truncation — never sliced so a
-    // partial address survives the cut. The address sits past the 500-char cap.
-    const addr = '0x' + 'a'.repeat(40)
-    const out = scrubMessage('y'.repeat(600) + addr)
-    expect(out).not.toContain(addr)
-    // And when the placeholder fits, it's present (redaction actually ran).
-    const out2 = scrubMessage('y'.repeat(100) + addr + 'z'.repeat(600))
-    expect(out2).not.toContain(addr)
-    expect(out2).toContain('0x[redacted-hex]')
-  })
-
-  it('uses a null prototype so __proto__ keys cannot pollute Object.prototype', () => {
-    const malicious = JSON.parse('{"__proto__": {"polluted": true}}')
-    const out = scrubValue(malicious) as Record<string, unknown>
-    expect(Object.getPrototypeOf(out)).toBeNull()
-    expect(({} as Record<string, unknown>).polluted).toBeUndefined()
-  })
-
-  it('renders bigint, function and symbol inertly', () => {
-    expect(scrubValue(10n)).toBe('10')
-    expect(scrubValue(() => 1)).toBe('[function]')
-    expect(scrubValue(Symbol('s'))).toBe('[symbol]')
-  })
-
-  it('reduces Error instances to name + message (no stack)', () => {
-    const out = scrubValue(new Error('kaboom')) as Record<string, unknown>
-    expect(out).toEqual({ name: 'Error', message: 'kaboom' })
-    expect(out.stack).toBeUndefined()
-  })
-
-  it('stops recursing past max depth', () => {
-    const deep = { a: { b: { c: { d: { e: { f: 1 } } } } } }
-    const out = scrubValue(deep) as Record<string, unknown>
-    // 5 levels down we hit the cap.
-    const a = out.a as Record<string, unknown>
-    const b = a.b as Record<string, unknown>
-    const c = b.c as Record<string, unknown>
-    const d = c.d as Record<string, unknown>
-    expect(d.e).toBe('[Truncated: max depth]')
-  })
-
-  it('scrubArgs maps every arg', () => {
-    const out = scrubArgs(['ok', { secret: 's', id: 1 }])
-    expect(out[0]).toBe('ok')
-    expect((out[1] as Record<string, unknown>).secret).toBe('[Redacted]')
-    expect((out[1] as Record<string, unknown>).id).toBe(1)
-  })
-
-  it('passes null/undefined/primitives through', () => {
-    expect(scrubValue(null)).toBeNull()
-    expect(scrubValue(undefined)).toBeUndefined()
-    expect(scrubValue(true)).toBe(true)
-    expect(scrubValue(5)).toBe(5)
-  })
-})

package/src/observability/scrub.ts

@@ -1,142 +0,0 @@
-/**
- * PII / secret scrubber for data leaving UWC through the observer seam.
- *
- * Security-first: the normalized `UWCTelemetryEvent` excludes signing payloads
- * and addresses by construction — its STRUCTURED fields have no slot for them
- * (§ telemetry.ts). This scrubber is the second line of defence for the two
- * surfaces that CAN still carry free-form data on the observer path: the
- * `WalletError.message` forwarded to `observer.onEvent`, and the `args` forwarded
- * to `observer.onLog`. (The console / custom-logger sink receives raw data — it's
- * local, not egress.)
- *
- * Two detection layers:
- *  - KEY-based redaction of sensitive object keys — substring match (not regex),
- *    avoiding the ReDoS class that Wiz flags on user-input regexes.
- *  - CONTENT-based redaction of secrets embedded in free-form strings (hex blobs,
- *    secret k/v params, bearer tokens) — via linear, single-quantifier regexes
- *    (see SECRET_CONTENT_PATTERNS) that carry no catastrophic-backtracking risk.
- */
-
-/**
- * Separator-free, lower-cased fragments that mark a value as sensitive. Keys are
- * normalized (separators stripped) before matching, so `walletPrivateKey`,
- * `private_key`, `x-api-key`, and `authToken` all hit the same short list. This
- * over-redacts by design (a `security`-first scrubber prefers a false redaction
- * to a leak).
- */
-const SENSITIVE_KEY_FRAGMENTS = [
-  'seed',
-  'mnemonic',
-  'privatekey',
-  'secret',
-  'password',
-  'passphrase',
-  'signature',
-  'message',
-  'payload',
-  'token',
-  'apikey',
-  'authorization',
-  'auth'
-]
-
-const MAX_STRING_LENGTH = 500
-const MAX_DEPTH = 4
-const REDACTED = '[Redacted]'
-
-function isSensitiveKey(key: string): boolean {
-  // Strip separators so `private_key` / `x-api-key` normalize to the bare form.
-  const normalized = key.toLowerCase().split('-').join('').split('_').join('')
-  return SENSITIVE_KEY_FRAGMENTS.some(fragment => normalized.includes(fragment))
-}
-
-// Content patterns for secrets embedded in FREE-FORM strings (error messages,
-// log args) where key-based redaction can't reach. All are linear, anchored,
-// single-quantifier expressions — no nested/overlapping quantifiers — so they
-// carry no catastrophic-backtracking (ReDoS) risk on attacker-controlled input.
-const SECRET_CONTENT_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
-  // 0x-prefixed hex blobs: EVM addresses (40 nibbles) and longer
-  // signatures/keys/hashes/calldata (64+). Over-redacts public hashes by design.
-  [/0x[a-fA-F0-9]{40,}/g, '0x[redacted-hex]'],
-  // `secret=…` / `token=…` / `key=…` query-string or k/v fragments.
-  [
-    /\b(token|key|secret|auth|sig|signature|password|passphrase|mnemonic|seed|apikey)=[^\s&"']+/gi,
-    '$1=[redacted]'
-  ],
-  // `Bearer <opaque>` / `Basic <opaque>` authorization values.
-  [/\b(bearer|basic)\s+[A-Za-z0-9._~+/-]+=*/gi, '$1 [redacted]']
-]
-
-/**
- * Redact secrets that live INSIDE a free-form string. Best-effort and
- * deliberately conservative toward over-redaction: a wallet error string can
- * embed an address, a reverted-tx calldata blob, or a URL with a token, none of
- * which key-based redaction sees. Two documented best-effort gaps, both left
- * unmatched to avoid destroying legitimate data:
- *   - Base58 (Solana) / TON `EQ…` addresses — indistinguishable from ordinary
- *     words without false positives.
- *   - BARE (non-`0x`) hex blobs — a raw 64-char hex string is far more often a
- *     legitimate id/hash than a secret, so only `0x`-prefixed hex is redacted.
- * Structured telemetry fields never carry addresses regardless (see telemetry.ts);
- * this pass only hardens the free-form `error.message` / log-arg surface.
- */
-function redactSecretsInString(input: string): string {
-  let out = input
-  for (const [pattern, replacement] of SECRET_CONTENT_PATTERNS) {
-    out = out.replace(pattern, replacement)
-  }
-  return out
-}
-
-/**
- * Recursively copy `value`, redacting sensitive object-keys, capping long
- * strings, and rendering non-serializable values inert. The returned objects use
- * a null prototype so a malicious `__proto__`/`constructor` key in attacker-shaped
- * input can't pollute `Object.prototype` downstream.
- */
-export function scrubValue(value: unknown, depth = 0): unknown {
-  if (depth > MAX_DEPTH) return '[Truncated: max depth]'
-
-  if (value === null || value === undefined) return value
-
-  const type = typeof value
-  if (type === 'string') {
-    // Redact embedded secrets BEFORE capping, so the cap can't slice a pattern
-    // in half and leak its tail.
-    const str = redactSecretsInString(value as string)
-    return str.length > MAX_STRING_LENGTH
-      ? str.slice(0, MAX_STRING_LENGTH) + '…[truncated]'
-      : str
-  }
-  if (type === 'number' || type === 'boolean') return value
-  if (type === 'bigint') return (value as bigint).toString()
-  if (type === 'function' || type === 'symbol') return `[${type}]`
-
-  if (Array.isArray(value)) {
-    return value.map(item => scrubValue(item, depth + 1))
-  }
-
-  if (type === 'object') {
-    // Error instances carry a useful message but also a stack we don't want.
-    if (value instanceof Error) {
-      return { name: value.name, message: scrubValue(value.message, depth + 1) }
-    }
-    const out: Record<string, unknown> = Object.create(null)
-    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
-      out[key] = isSensitiveKey(key) ? REDACTED : scrubValue(val, depth + 1)
-    }
-    return out
-  }
-
-  return '[Unserializable]'
-}
-
-/** Scrub a free-form error message (string in → capped string out). */
-export function scrubMessage(message: string): string {
-  return scrubValue(message) as string
-}
-
-/** Scrub a variadic `args` array before it reaches `observer.onLog`. */
-export function scrubArgs(args: unknown[]): unknown[] {
-  return args.map(arg => scrubValue(arg))
-}

package/src/observability/telemetry.test.ts

@@ -1,134 +0,0 @@
-import { describe, it, expect, afterEach, vi } from 'vitest'
-import type { Session } from '@meshconnect/uwc-types'
-import {
-  normalizeEvent,
-  deriveWalletFlowType,
-  derivePlatform
-} from './telemetry'
-
-describe('deriveWalletFlowType', () => {
-  it('maps injected to extension on desktop, in-wallet-browser on mobile', () => {
-    expect(deriveWalletFlowType('injected', 'desktop')).toBe(
-      'browser_extension_flow'
-    )
-    expect(deriveWalletFlowType('injected', 'mobile')).toBe(
-      'in_wallet_browser_flow'
-    )
-    expect(deriveWalletFlowType('injected', 'webview')).toBe(
-      'in_wallet_browser_flow'
-    )
-  })
-
-  it('maps walletConnect to QR on desktop, deeplink on mobile', () => {
-    expect(deriveWalletFlowType('walletConnect', 'desktop')).toBe(
-      'wallet_connect_qr_flow'
-    )
-    expect(deriveWalletFlowType('walletConnect', 'mobile')).toBe(
-      'wallet_connect_deep_link_flow'
-    )
-  })
-
-  it('maps tonConnect to QR on desktop, deeplink on mobile', () => {
-    expect(deriveWalletFlowType('tonConnect', 'desktop')).toBe(
-      'ton_connect_qr_flow'
-    )
-    expect(deriveWalletFlowType('tonConnect', 'mobile')).toBe(
-      'ton_connect_deep_link_flow'
-    )
-  })
-})
-
-describe('derivePlatform', () => {
-  afterEach(() => vi.unstubAllGlobals())
-
-  it('returns desktop for a desktop UA', () => {
-    vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Macintosh)' })
-    expect(derivePlatform()).toBe('desktop')
-  })
-
-  it('returns mobile for an iOS Safari UA', () => {
-    vi.stubGlobal('navigator', {
-      userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0) Safari/604.1'
-    })
-    expect(derivePlatform()).toBe('mobile')
-  })
-
-  it('returns webview for an Android in-app browser UA (; wv)', () => {
-    vi.stubGlobal('navigator', {
-      userAgent: 'Mozilla/5.0 (Linux; Android 13; wv) Chrome/120'
-    })
-    expect(derivePlatform()).toBe('webview')
-  })
-})
-
-describe('normalizeEvent', () => {
-  const SDK_SESSION = 'sess-1'
-  const NOW = 1_700_000_000_000
-
-  it('reduces a `connected` session to facets and never leaks the address', () => {
-    const session = {
-      connectionMode: 'injected',
-      activeNetwork: { namespace: 'eip155', id: 'eip155:1', name: 'Ethereum' },
-      activeWallet: { id: 'metamask', name: 'MetaMask' },
-      activeAddress: '0xDEADBEEFcafe1234567890',
-      publicKey: 'pubkey-should-not-leak'
-    } as unknown as Session
-
-    const out = normalizeEvent('connected', { session }, SDK_SESSION, NOW)
-
-    expect(out.namespace).toBe('eip155')
-    expect(out.chainId).toBe('eip155:1')
-    expect(out.walletId).toBe('metamask')
-    expect(out.sdkSessionId).toBe(SDK_SESSION)
-    expect(out.timestamp).toBe(NOW)
-    // The address / pubkey must be structurally absent from the record.
-    const serialized = JSON.stringify(out)
-    expect(serialized).not.toContain('0xDEADBEEF')
-    expect(serialized).not.toContain('pubkey-should-not-leak')
-  })
-
-  it('scrubs the error message on `error` events', () => {
-    const out = normalizeEvent(
-      'error',
-      {
-        error: { type: 'unknown', message: 'x'.repeat(800) },
-        operation: 'signMessage'
-      },
-      SDK_SESSION,
-      NOW
-    )
-    expect(out.operation).toBe('signMessage')
-    expect(out.error?.message.endsWith('…[truncated]')).toBe(true)
-  })
-
-  it('passes handoff facets through for awaitingWallet', () => {
-    const out = normalizeEvent(
-      'awaitingWallet',
-      {
-        operation: 'sendTransaction',
-        connectionMode: 'walletConnect',
-        walletId: 'rainbow',
-        namespace: 'eip155',
-        chainId: 'eip155:8453',
-        handoffId: 'h-1',
-        walletFlowType: 'wallet_connect_deep_link_flow',
-        platform: 'mobile',
-        timestamp: NOW
-      },
-      SDK_SESSION,
-      NOW
-    )
-    expect(out.handoffId).toBe('h-1')
-    expect(out.walletFlowType).toBe('wallet_connect_deep_link_flow')
-    expect(out.platform).toBe('mobile')
-  })
-
-  it('collapses noisy/unknown events to name only', () => {
-    const out = normalizeEvent('ready', undefined, SDK_SESSION, NOW)
-    expect(out).toEqual({
-      name: 'ready',
-      sdkSessionId: SDK_SESSION,
-      timestamp: NOW
-    })
-  })
-})

package/src/observability/telemetry.ts

@@ -1,211 +0,0 @@
-import type {
-  ConnectionMode,
-  WalletError,
-  WalletFlowType,
-  Platform,
-  LogLevel,
-  Namespace,
-  NetworkId
-} from '@meshconnect/uwc-types'
-import type { UWCEventName, UWCEventMap, UWCOperation } from '../events'
-import { scrubMessage } from './scrub'
-
-/**
- * A normalized, PII-safe telemetry record derived from a `UWCEventMap` event.
- *
- * This is the ONLY shape that reaches `observer.onEvent`. It is the PII boundary:
- * it has no field for a signing payload, signature, raw transaction, or wallet
- * address — leaking those is structurally impossible, not merely discouraged.
- */
-export interface UWCTelemetryEvent {
-  /** The originating event name. */
-  name: UWCEventName
-  /** Per-connector-instance correlation id (stamped on every event). */
-  sdkSessionId: string
-  /** ms since epoch when the record was produced. */
-  timestamp: number
-  /** Wallet-boundary op, when the event relates to one. */
-  operation?: UWCOperation | undefined
-  connectionMode?: ConnectionMode | undefined
-  /** CAIP namespace (eip155 | solana | tron | tvm …) — never an address. */
-  namespace?: Namespace | undefined
-  /** CAIP chain id (e.g. `eip155:1`) — never an address. */
-  chainId?: NetworkId | undefined
-  /** Catalog wallet id — never an address. */
-  walletId?: string | undefined
-  /** Correlates a handoff start with its terminal. */
-  handoffId?: string | undefined
-  durationMs?: number | undefined
-  walletFlowType?: WalletFlowType | undefined
-  platform?: Platform | undefined
-  /** Present on failure events. `message` is scrubbed before egress. */
-  error?: WalletError | undefined
-  /** Log level, present only for `name === 'log'`. */
-  level?: LogLevel | undefined
-}
-
-/**
- * Vendor-agnostic telemetry sink. Consumers implement; UWC ships no vendor SDK.
- * Both methods are optional and called best-effort (throws are swallowed upstream).
- *
- * CONTRACT — both methods are invoked **synchronously on the wallet-operation
- * path**. A terminal event (e.g. `walletSucceeded`) fires between the wallet
- * returning a result and that result reaching the caller, so a slow handler adds
- * latency to connect / sign / sendTransaction. Keep handlers **non-blocking**:
- * hand off to a queue-backed sink (Datadog `addAction`, Segment `track`, etc. are
- * already non-blocking) or defer heavy work yourself — e.g.
- * `onEvent: e => queueMicrotask(() => doHeavyWork(e))`. Do not perform synchronous
- * network/IO or expensive serialization inline.
- */
-export interface UWCObserver {
-  /** A normalized, PII-safe event. Forward to Datadog / Amplitude / Segment / … (non-blocking). */
-  onEvent?(event: UWCTelemetryEvent): void
-  /** A log line (all levels). `args` is already scrubbed. Keep non-blocking. */
-  onLog?(level: LogLevel, message: string, args: unknown[]): void
-}
-
-/**
- * Best-effort coarse runtime surface. HEURISTIC — user agents lie and in-app
- * browsers are hard to detect; treat `webview` as a hint, not a guarantee.
- * Never returns the raw UA (PII / high-cardinality).
- */
-export function derivePlatform(): Platform {
-  if (typeof navigator === 'undefined' || !navigator.userAgent) return 'unknown'
-  const ua = navigator.userAgent
-  const isIOS = /iPhone|iPad|iPod/i.test(ua)
-  const isAndroid = /Android/i.test(ua)
-  // Android in-app browsers tag the UA with `; wv`; iOS WKWebViews lack `Safari`.
-  const isWebview =
-    (isAndroid && /; wv\)/i.test(ua)) || (isIOS && !/Safari/i.test(ua))
-  if (isWebview) return 'webview'
-  if (isIOS || isAndroid) return 'mobile'
-  return 'desktop'
-}
-
-/**
- * Derive the flow taxonomy from connection mode + surface. HEURISTIC — UWC does
- * not always know whether a WalletConnect handoff used a deeplink vs a QR scan;
- * we infer from the platform (mobile ⇒ deeplink, desktop ⇒ QR), matching link-v2's
- * historical intent. Consumers with better context may override downstream.
- */
-export function deriveWalletFlowType(
-  connectionMode: ConnectionMode,
-  platform: Platform
-): WalletFlowType {
-  const isDesktop = platform === 'desktop'
-  switch (connectionMode) {
-    case 'injected':
-      // Injected on a phone almost always means we're inside a wallet's browser.
-      return isDesktop ? 'browser_extension_flow' : 'in_wallet_browser_flow'
-    case 'walletConnect':
-      return isDesktop
-        ? 'wallet_connect_qr_flow'
-        : 'wallet_connect_deep_link_flow'
-    case 'tonConnect':
-      return isDesktop ? 'ton_connect_qr_flow' : 'ton_connect_deep_link_flow'
-    default:
-      return 'unknown'
-  }
-}
-
-/**
- * Map a raw `UWCEventMap` event to its PII-safe `UWCTelemetryEvent`.
- *
- * Per-event allow-listing: only known-safe fields are copied. Payloads carrying a
- * `Session`/`Network` (which include the wallet address) are reduced to
- * `namespace` + `chainId` + `walletId`. Unknown/noisy payloads collapse to just
- * the name. `error.message` is scrubbed.
- */
-export function normalizeEvent<K extends UWCEventName>(
-  name: K,
-  data: UWCEventMap[K],
-  sdkSessionId: string,
-  now: number
-): UWCTelemetryEvent {
-  const base: UWCTelemetryEvent = { name, sdkSessionId, timestamp: now }
-
-  switch (name) {
-    case 'connecting': {
-      const d = data as UWCEventMap['connecting']
-      return {
-        ...base,
-        operation: 'connect',
-        connectionMode: d.connectionMode,
-        walletId: d.walletId
-      }
-    }
-    case 'connected':
-    case 'sessionChanged': {
-      const d = data as UWCEventMap['connected']
-      const session = d.session
-      return {
-        ...base,
-        connectionMode: session.connectionMode ?? undefined,
-        namespace: session.activeNetwork?.namespace,
-        chainId: session.activeNetwork?.id,
-        walletId: session.activeWallet?.id
-      }
-    }
-    case 'networkSwitched': {
-      const d = data as UWCEventMap['networkSwitched']
-      return {
-        ...base,
-        operation: 'switchNetwork',
-        namespace: d.network.namespace,
-        chainId: d.network.id
-      }
-    }
-    case 'connectionUri': {
-      // Carry the mode but NEVER the URI itself (a relay/pairing string).
-      const d = data as UWCEventMap['connectionUri']
-      return { ...base, connectionMode: d.connectionMode }
-    }
-    case 'error': {
-      const d = data as UWCEventMap['error']
-      return {
-        ...base,
-        operation: d.operation,
-        error: { type: d.error.type, message: scrubMessage(d.error.message) }
-      }
-    }
-    case 'awaitingWallet': {
-      const d = data as UWCEventMap['awaitingWallet']
-      return {
-        ...base,
-        operation: d.operation,
-        connectionMode: d.connectionMode,
-        walletId: d.walletId,
-        namespace: d.namespace,
-        chainId: d.chainId,
-        handoffId: d.handoffId,
-        walletFlowType: d.walletFlowType,
-        platform: d.platform
-      }
-    }
-    case 'walletSucceeded':
-    case 'walletRejected':
-    case 'walletTimedOut': {
-      const d = data as UWCEventMap['walletSucceeded']
-      return {
-        ...base,
-        operation: d.operation,
-        handoffId: d.handoffId,
-        durationMs: d.durationMs
-      }
-    }
-    case 'walletFailed': {
-      const d = data as UWCEventMap['walletFailed']
-      return {
-        ...base,
-        operation: d.operation,
-        handoffId: d.handoffId,
-        durationMs: d.durationMs,
-        error: { type: d.error.type, message: scrubMessage(d.error.message) }
-      }
-    }
-    default:
-      // ready / walletsDetected / disconnected / networkSwitching /
-      // capabilitiesUpdated / change / log — name only (log goes via onLog).
-      return base
-  }
-}