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

package/src/observability/instrument-handoff.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { WalletConnectorError } from '@meshconnect/uwc-types'
+import { EventManager } from '../managers/event-manager'
+import { instrumentHandoff, type HandoffContext } from './instrument-handoff'
+
+const CTX: HandoffContext = {
+  operation: 'signMessage',
+  connectionMode: 'injected',
+  walletId: 'metamask',
+  namespace: 'eip155',
+  chainId: 'eip155:1'
+}
+
+function record(em: EventManager) {
+  const seen: Array<{ name: string; data: unknown }> = []
+  for (const name of [
+    'awaitingWallet',
+    'walletSucceeded',
+    'walletRejected',
+    'walletFailed',
+    'walletTimedOut'
+  ] as const) {
+    em.on(name, data => seen.push({ name, data }))
+  }
+  return seen
+}
+
+describe('instrumentHandoff', () => {
+  it('emits awaitingWallet then walletSucceeded on success', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    const result = await instrumentHandoff(
+      { eventManager: em, timeoutMs: 0 },
+      CTX,
+      async () => 'sig'
+    )
+    expect(result).toBe('sig')
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletSucceeded'])
+    const start = seen[0].data as { handoffId: string }
+    const end = seen[1].data as { handoffId: string }
+    expect(end.handoffId).toBe(start.handoffId)
+  })
+
+  it('emits walletRejected for an explicit user rejection', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw new WalletConnectorError({
+          type: 'rejected',
+          message: 'user said no'
+        })
+      })
+    ).rejects.toThrow('user said no')
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletRejected'])
+  })
+
+  it('emits walletRejected for a raw EIP-1193 4001', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw Object.assign(new Error('rejected'), { code: 4001 })
+      })
+    ).rejects.toThrow()
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletRejected'])
+  })
+
+  it('emits walletFailed (with scrubbed error) for any other error', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw new Error('rpc exploded')
+      })
+    ).rejects.toThrow('rpc exploded')
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet', 'walletFailed'])
+    const failed = seen[1].data as { error: { type: string; message: string } }
+    expect(failed.error.type).toBe('unknown')
+    expect(failed.error.message).toBe('rpc exploded')
+  })
+
+  it('emits NO terminal for an intentional abort', async () => {
+    const em = new EventManager()
+    const seen = record(em)
+    await expect(
+      instrumentHandoff({ eventManager: em, timeoutMs: 0 }, CTX, async () => {
+        throw new DOMException('Aborted', 'AbortError')
+      })
+    ).rejects.toThrow()
+    expect(seen.map(s => s.name)).toEqual(['awaitingWallet'])
+  })
+
+  describe('timeout marker', () => {
+    beforeEach(() => vi.useFakeTimers())
+    afterEach(() => vi.useRealTimers())
+
+    it('fires walletTimedOut while pending, then still resolves with walletSucceeded', async () => {
+      const em = new EventManager()
+      const seen = record(em)
+      let resolveFn: (v: string) => void = () => {}
+      const promise = instrumentHandoff(
+        { eventManager: em, timeoutMs: 1000 },
+        CTX,
+        () => new Promise<string>(r => (resolveFn = r))
+      )
+      // Deadline passes with the op still pending → side marker fires.
+      await vi.advanceTimersByTimeAsync(1000)
+      expect(seen.map(s => s.name)).toContain('walletTimedOut')
+      // The op then completes → real terminal still fires.
+      resolveFn('late-sig')
+      await expect(promise).resolves.toBe('late-sig')
+      expect(seen.map(s => s.name)).toEqual([
+        'awaitingWallet',
+        'walletTimedOut',
+        'walletSucceeded'
+      ])
+    })
+
+    it('does NOT fire walletTimedOut for an op that settles before the deadline', async () => {
+      const em = new EventManager()
+      const seen = record(em)
+      await instrumentHandoff(
+        { eventManager: em, timeoutMs: 1000 },
+        CTX,
+        async () => 'fast'
+      )
+      await vi.advanceTimersByTimeAsync(5000)
+      expect(seen.map(s => s.name)).toEqual([
+        'awaitingWallet',
+        'walletSucceeded'
+      ])
+    })
+
+    it('never arms the timer for tonConnect (already bounded by TON)', async () => {
+      const em = new EventManager()
+      const seen = record(em)
+      let resolveFn: (v: string) => void = () => {}
+      const promise = instrumentHandoff(
+        { eventManager: em, timeoutMs: 1000 },
+        { ...CTX, connectionMode: 'tonConnect' },
+        () => new Promise<string>(r => (resolveFn = r))
+      )
+      await vi.advanceTimersByTimeAsync(5000)
+      expect(seen.map(s => s.name)).not.toContain('walletTimedOut')
+      resolveFn('ok')
+      await promise
+    })
+  })
+})

package/src/observability/instrument-handoff.ts

@@ -0,0 +1,122 @@
+import type {
+  ConnectionMode,
+  Namespace,
+  NetworkId
+} from '@meshconnect/uwc-types'
+import type { EventManager } from '../managers/event-manager'
+import type { UWCOperation } from '../events'
+import { generateId } from '../utils/id'
+import {
+  isAbortError,
+  isUserRejection,
+  toWalletError
+} from '../utils/to-wallet-error'
+import { derivePlatform, deriveWalletFlowType } from './telemetry'
+
+/** Routing facets known at the moment of a wallet handoff. No address, no payload. */
+export interface HandoffContext {
+  operation: UWCOperation
+  connectionMode: ConnectionMode
+  walletId?: string | undefined
+  namespace?: Namespace | undefined
+  chainId?: NetworkId | undefined
+}
+
+export interface InstrumentHandoffOptions {
+  eventManager: EventManager
+  /**
+   * Deadline after which `walletTimedOut` fires as a SIDE marker (never rejects).
+   * `0` disables the marker. `tonConnect` is always skipped — TON bounds its own
+   * wallet response internally, so a second observational timer would be noise.
+   */
+  timeoutMs: number
+  /** Clock injectable for deterministic tests. */
+  now?: () => number
+}
+
+/**
+ * Instrument one wallet-boundary op so the blind window is measured.
+ *
+ * Emits `awaitingWallet` immediately (before the await that hands control to the
+ * wallet), then exactly one terminal — `walletSucceeded` (success),
+ * `walletRejected` (explicit user no), or `walletFailed` (any other error) — all
+ * carrying the same `handoffId` and a `durationMs`. An intentional abort emits no
+ * terminal (the caller cancelled; it isn't a wallet outcome).
+ *
+ * A non-cancelling `walletTimedOut` marker fires if the deadline passes while the
+ * op is still pending; it is cleared the instant the op settles, so a fast op
+ * never false-fires it, and it NEVER rejects/aborts/mutates state — the wrapped
+ * promise stays the single terminal source of truth. This is a deliberate
+ * deviation from TON's cancelling `withWalletResponseTimeout`.
+ */
+export async function instrumentHandoff<T>(
+  options: InstrumentHandoffOptions,
+  context: HandoffContext,
+  fn: () => Promise<T>
+): Promise<T> {
+  const { eventManager, timeoutMs } = options
+  const now = options.now ?? Date.now
+
+  const handoffId = generateId()
+  const platform = derivePlatform()
+  const start = now()
+
+  eventManager.emit('awaitingWallet', {
+    operation: context.operation,
+    connectionMode: context.connectionMode,
+    walletId: context.walletId,
+    namespace: context.namespace,
+    chainId: context.chainId,
+    handoffId,
+    walletFlowType: deriveWalletFlowType(context.connectionMode, platform),
+    platform,
+    timestamp: start
+  })
+
+  const shouldTime = timeoutMs > 0 && context.connectionMode !== 'tonConnect'
+  const timer: ReturnType<typeof setTimeout> | undefined = shouldTime
+    ? setTimeout(() => {
+        eventManager.emit('walletTimedOut', {
+          handoffId,
+          operation: context.operation,
+          durationMs: now() - start
+        })
+      }, timeoutMs)
+    : undefined
+
+  try {
+    const result = await fn()
+    eventManager.emit('walletSucceeded', {
+      handoffId,
+      operation: context.operation,
+      durationMs: now() - start
+    })
+    return result
+  } catch (error) {
+    // Caller-driven cancellation isn't a wallet outcome — leave it unterminated,
+    // mirroring the façade's `emitError` AbortError skip. Checked BEFORE rejection
+    // is safe: real user rejections surface as WalletConnectorError{rejected} or
+    // EIP-1193 4001 (see isUserRejection), never as an AbortError — within UWC's
+    // dependency surface AbortError is produced only by the caller's AbortSignal.
+    if (isAbortError(error)) throw error
+
+    const durationMs = now() - start
+    if (isUserRejection(error)) {
+      eventManager.emit('walletRejected', {
+        handoffId,
+        operation: context.operation,
+        durationMs
+      })
+    } else {
+      eventManager.emit('walletFailed', {
+        handoffId,
+        operation: context.operation,
+        durationMs,
+        error: toWalletError(error)
+      })
+    }
+    throw error
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}

package/src/observability/scrub.test.ts

@@ -0,0 +1,109 @@
+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

@@ -0,0 +1,142 @@
+/**
+ * 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

@@ -0,0 +1,134 @@
+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
+    })
+  })
+})