@spacesops/wdk-react-native-core 1.0.0-beta.40

package/src/utils/errorUtils.ts

@@ -0,0 +1,300 @@
+/**
+ * Error utility functions for consistent error handling
+ * 
+ * ## Usage Guidelines
+ * 
+ * **For Services**: Use `handleServiceError()` from `errorHandling.ts` - this provides
+ * consistent normalization and logging for service-layer errors. Errors are NOT sanitized
+ * (sanitizeLevel: false) because services log internally and need full error details.
+ * 
+ * **For Hooks/UI**: Use `normalizeError()` directly with appropriate sanitization level.
+ * Hooks should sanitize errors before exposing them to UI components to prevent information leakage.
+ * 
+ * @example Service usage (use handleServiceError instead):
+ * ```typescript
+ * import { handleServiceError } from './errorHandling'
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   handleServiceError(error, 'MyService', 'operationName', { context })
+ * }
+ * ```
+ * 
+ * @example Hook/UI usage:
+ * ```typescript
+ * import { normalizeError } from './errorUtils'
+ * try {
+ *   await someOperation()
+ * } catch (error) {
+ *   const normalized = normalizeError(error, true, { component: 'MyHook', operation: 'fetchData' })
+ *   setError(normalized.message)
+ * }
+ * ```
+ */
+
+/**
+ * Sanitization levels for error messages
+ */
+export enum SanitizationLevel {
+  NONE = 'none',           // No sanitization (internal debugging only)
+  DEVELOPMENT = 'dev',     // Mask sensitive strings but show structure
+  PRODUCTION = 'prod',     // Aggressive sanitization
+}
+
+/**
+ * Context-aware sensitive patterns
+ * More specific patterns to avoid false positives while catching real sensitive data
+ */
+const SENSITIVE_PATTERNS = [
+  // Cryptographic keys and secrets (more specific)
+  /\b(encryption[_-]?key|encryptionKey|encrypted[_-]?seed|encryptedSeed|secret[_-]?key|private[_-]?key)\s*[:=]\s*([a-f0-9]{32,}|[A-Za-z0-9+/]{40,})/gi,
+  // Mnemonic phrases (12 or 24 words) - allow alphanumeric words
+  /\b(mnemonic|seed[_-]?phrase|recovery[_-]?phrase)\s*[:=]\s*([a-zA-Z0-9]+\s+){11,23}[a-zA-Z0-9]+/gi,
+  // Base64 encoded keys (long base64 strings)
+  /[A-Za-z0-9+/]{40,}={0,2}/g,
+  // Hex strings that look like keys (32+ chars, even length)
+  /\b0x?[a-f0-9]{32,}\b/gi,
+  // File paths with sensitive names
+  /file:\/\/[^\s]*(key|secret|password|credential|seed|mnemonic|private)[^\s]*/gi,
+  // Paths containing sensitive directories
+  /\/(?:private|secret|keys|credentials|seeds|mnemonics)\/[^\s]+/gi,
+  // API tokens and keys in various formats
+  /\b(api[_-]?key|access[_-]?token|bearer[_-]?token|auth[_-]?token)\s*[:=]\s*[^\s]{20,}/gi,
+  // Passwords (but not "password" as a word)
+  /\bpassword\s*[:=]\s*[^\s]{8,}/gi,
+]
+
+/**
+ * Whitelist of safe patterns that should NOT be sanitized
+ * These are common non-sensitive terms that might match sensitive patterns
+ */
+const SAFE_PATTERNS = [
+  /\b(public[_-]?key|publicKey)\b/gi, // Public keys are safe
+  /\b(error|Error|ERROR)\b/g, // Error messages themselves
+  /\b(function|Function|const|let|var)\b/g, // Code keywords
+  /\b(undefined|null|true|false)\b/g, // JavaScript literals
+]
+
+/**
+ * Check if a string matches a safe pattern (should not be sanitized)
+ */
+function isSafePattern(text: string): boolean {
+  return SAFE_PATTERNS.some(pattern => pattern.test(text))
+}
+
+/**
+ * Mask sensitive string patterns (hex/base64) for development mode
+ */
+function maskSensitiveStrings(message: string): string {
+  return message
+    .replace(/\b0x?[a-f0-9]{32,}\b/gi, (match) => {
+      if (match.length <= 20) return match
+      return `${match.substring(0, 8)}...${match.substring(match.length - 4)}`
+    })
+    .replace(/\b[A-Za-z0-9+/]{40,}={0,2}\b/g, (match) => {
+      return `${match.substring(0, 8)}...${match.substring(match.length - 4)}`
+    })
+}
+
+/**
+ * Remove file paths from error messages
+ */
+function removeFilePaths(message: string): string {
+  return message
+    .replace(/file:\/\/[^\s]+/gi, '[file path]')
+    .replace(/\/[^\s]+\/[^\s]+/g, '[path]')
+}
+
+/**
+ * Get replacement text for a sensitive pattern match
+ */
+function getSensitiveReplacement(match: string): string {
+  const lowerMatch = match.toLowerCase()
+  if (lowerMatch.includes('encryption') || lowerMatch.includes('encrypted')) {
+    return '[encryption data]'
+  }
+  if (lowerMatch.includes('mnemonic') || lowerMatch.includes('seed phrase')) {
+    return '[mnemonic phrase]'
+  }
+  if (lowerMatch.includes('key') && !lowerMatch.includes('public')) {
+    return '[key]'
+  }
+  if (lowerMatch.includes('token')) {
+    return '[token]'
+  }
+  if (lowerMatch.includes('password')) {
+    return '[password]'
+  }
+  if (lowerMatch.includes('secret')) {
+    return '[secret]'
+  }
+  if (/[a-f0-9]{32,}/i.test(match) || /[A-Za-z0-9+/]{40,}/.test(match)) {
+    return '[sensitive data]'
+  }
+  return '[sensitive]'
+}
+
+/**
+ * Apply sensitive pattern sanitization
+ */
+function applySensitivePatternSanitization(message: string): string {
+  let sanitized = message
+  for (const pattern of SENSITIVE_PATTERNS) {
+    sanitized = sanitized.replace(pattern, (match) => {
+      if (isSafePattern(match)) {
+        return match
+      }
+      return getSensitiveReplacement(match)
+    })
+  }
+  return sanitized
+}
+
+/**
+ * Sanitize error message to prevent information leakage
+ * Removes or masks sensitive information while preserving useful debugging info
+ * 
+ * @param message - Error message to sanitize
+ * @param isDevelopment - Whether we're in development mode (less sanitization)
+ * @param context - Optional context about where the error occurred (for better sanitization)
+ * @returns Sanitized error message
+ */
+export function sanitizeErrorMessage(
+  message: string,
+  isDevelopment = false,
+  context?: { operation?: string; component?: string }
+): string {
+  if (isDevelopment) {
+    return maskSensitiveStrings(message)
+  }
+
+  // In production, be more aggressive with sanitization
+  let sanitized = removeFilePaths(message)
+  sanitized = applySensitivePatternSanitization(sanitized)
+  
+  // Additional cleanup: remove any remaining long hex/base64 strings
+  sanitized = sanitized.replace(/\b0x?[a-f0-9]{32,}\b/gi, '[hex string]')
+  sanitized = sanitized.replace(/\b[A-Za-z0-9+/]{40,}={0,2}\b/g, '[base64 string]')
+
+  return sanitized
+}
+
+/**
+ * Normalize error to Error instance
+ * Converts any error-like value to a proper Error object
+ * Always sanitizes the error message (with different levels) to prevent information leakage
+ * 
+ * @param error - Error to normalize
+ * @param sanitizeLevel - Sanitization level or boolean (default: PRODUCTION in production, DEVELOPMENT in dev)
+ * @param context - Optional context about where the error occurred
+ * @returns Normalized Error instance
+ */
+export function normalizeError(
+  error: unknown,
+  sanitizeLevel: SanitizationLevel | boolean = process.env.NODE_ENV === 'production' 
+    ? SanitizationLevel.PRODUCTION 
+    : SanitizationLevel.DEVELOPMENT,
+  context?: { operation?: string; component?: string; [key: string]: unknown }
+): Error {
+  let errorMessage: string
+
+  if (error instanceof Error) {
+    errorMessage = error.message
+  } else if (typeof error === 'string') {
+    errorMessage = error
+  } else if (error && typeof error === 'object' && 'message' in error) {
+    errorMessage = String(error.message)
+  } else {
+    errorMessage = String(error)
+  }
+
+  // Always sanitize, but with different levels
+  const level = typeof sanitizeLevel === 'boolean' 
+    ? (sanitizeLevel ? SanitizationLevel.PRODUCTION : SanitizationLevel.NONE)
+    : sanitizeLevel
+
+  if (level !== SanitizationLevel.NONE) {
+    errorMessage = sanitizeErrorMessage(
+      errorMessage,
+      level === SanitizationLevel.DEVELOPMENT,
+      context
+    )
+  }
+
+  const normalizedError = new Error(errorMessage)
+  
+  // Preserve error name and stack if available
+  if (error instanceof Error) {
+    normalizedError.name = error.name
+    // Sanitize stack trace based on level
+    if (error.stack) {
+      if (level !== SanitizationLevel.NONE) {
+        // Mask file paths and sensitive data in stack traces
+        normalizedError.stack = sanitizeErrorMessage(error.stack, level === SanitizationLevel.DEVELOPMENT, context)
+      } else {
+        normalizedError.stack = error.stack
+      }
+    }
+  }
+
+  return normalizedError
+}
+
+/**
+ * Get error message from any error-like value
+ */
+export function getErrorMessage(error: unknown): string {
+  return normalizeError(error).message
+}
+
+/**
+ * Check if error is a specific type
+ */
+export function isErrorType(error: unknown, typeName: string): boolean {
+  return error instanceof Error && error.name === typeName
+}
+
+/**
+ * Create a standardized error with context
+ */
+export function createContextualError(
+  message: string,
+  context?: Record<string, unknown>
+): Error {
+  const error = new Error(message)
+  if (context) {
+    Object.assign(error, { context })
+  }
+  return error
+}
+
+/**
+ * Check if an error is an authentication error
+ * Used to prevent automatic retries when authentication fails
+ * 
+ * @param error - Error to check
+ * @returns true if the error is an authentication error
+ */
+export function isAuthenticationError(error: unknown): boolean {
+  // Check if it's an AuthenticationError instance from secure storage
+  if (error && typeof error === 'object' && 'constructor' in error) {
+    const errorName = error.constructor.name
+    if (errorName === 'AuthenticationError') {
+      return true
+    }
+  }
+
+  // Check if it's an Error instance with authentication-related properties
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase()
+    return (
+      error.name === 'AuthenticationError' ||
+      msg.includes('authentication') ||
+      msg.includes('biometric') ||
+      msg.includes('authentication required but failed')
+    )
+  }
+
+  return false
+}
+

package/src/utils/initializationState.ts

@@ -0,0 +1,242 @@
+/**
+ * Worklet Initialization State Machine
+ * 
+ * Represents the state of the worklet runtime initialization (global, happens once).
+ * This is separate from wallet loading, which happens per-identifier.
+ */
+
+/**
+ * Worklet initialization status enum
+ * 
+ * Represents the current state of the worklet runtime initialization.
+ * The worklet is initialized once (global), but wallets are loaded per-identifier.
+ * 
+ * Flow:
+ * 1. IDLE -> STARTING_WORKLET (worklet initialization begins)
+ * 2. STARTING_WORKLET -> WORKLET_READY (worklet runtime ready, can now load wallets)
+ * 
+ * After WORKLET_READY, you can load different wallets (per identifier).
+ * Wallet loading state is separate - see walletState in WdkAppContextValue.
+ */
+export enum InitializationStatus {
+  /** Initial state - worklet not started */
+  IDLE = 'idle',
+  /** Worklet runtime is starting (happens once, global) */
+  STARTING_WORKLET = 'starting_worklet',
+  /** Worklet is ready - can now load wallets (per identifier) */
+  WORKLET_READY = 'worklet_ready',
+  /** Error state - worklet initialization failed */
+  ERROR = 'error',
+}
+
+/**
+ * App-level status enum
+ * 
+ * Represents the combined state of worklet initialization and wallet loading.
+ * This is a convenience enum for app-level "is ready?" checks.
+ * 
+ * For granular control, use workletState and walletState separately.
+ */
+export enum AppStatus {
+  /** Worklet not started */
+  IDLE = 'idle',
+  /** Worklet is starting */
+  STARTING_WORKLET = 'starting_worklet',
+  /** Worklet ready, no wallet loaded */
+  WORKLET_READY = 'worklet_ready',
+  /** Loading a wallet (checking existence, decrypting, initializing) */
+  LOADING_WALLET = 'loading_wallet',
+  /** Fully ready - worklet started, wallet loaded, addresses available */
+  READY = 'ready',
+  /** Error state - worklet or wallet error */
+  ERROR = 'error',
+}
+
+/**
+ * Helper to check if status represents an error state
+ */
+export function isErrorStatus(status: InitializationStatus): boolean {
+  return status === InitializationStatus.ERROR
+}
+
+/**
+ * Helper to check if worklet initialization is complete and ready
+ */
+export function isReadyStatus(status: InitializationStatus): boolean {
+  return status === InitializationStatus.WORKLET_READY
+}
+
+/**
+ * Helper to check if worklet initialization is in progress
+ */
+export function isInProgressStatus(status: InitializationStatus): boolean {
+  return status === InitializationStatus.STARTING_WORKLET
+}
+
+/**
+ * Helper to check if app status represents an in-progress state
+ */
+export function isAppInProgressStatus(status: AppStatus): boolean {
+  return [
+    AppStatus.STARTING_WORKLET,
+    AppStatus.LOADING_WALLET,
+  ].includes(status)
+}
+
+/**
+ * Helper to check if app is ready (worklet + wallet both ready)
+ */
+export function isAppReadyStatus(status: AppStatus): boolean {
+  return status === AppStatus.READY
+}
+
+/**
+ * Helper to check if worklet has started (worklet runtime is ready)
+ * Once worklet is ready, you can load wallets (per identifier)
+ */
+export function hasWorkletStarted(status: InitializationStatus): boolean {
+  return [
+    InitializationStatus.WORKLET_READY,
+    InitializationStatus.ERROR,
+  ].includes(status)
+}
+
+/**
+ * Helper to check if wallet operations can be performed
+ * Returns true when worklet is ready (wallets can be loaded per identifier)
+ */
+export function canLoadWallet(status: InitializationStatus): boolean {
+  return status === InitializationStatus.WORKLET_READY
+}
+
+/**
+ * Helper to check if app status indicates worklet has started
+ */
+export function hasWorkletStartedApp(status: AppStatus): boolean {
+  return [
+    AppStatus.WORKLET_READY,
+    AppStatus.LOADING_WALLET,
+    AppStatus.READY,
+    AppStatus.ERROR,
+  ].includes(status)
+}
+
+/**
+ * Helper to check if wallet operations can be performed based on app status
+ */
+export function canLoadWalletApp(status: AppStatus): boolean {
+  return [
+    AppStatus.WORKLET_READY,
+    AppStatus.LOADING_WALLET,
+    AppStatus.READY,
+  ].includes(status)
+}
+
+/**
+ * Get human-readable worklet initialization status message
+ */
+export function getStatusMessage(status: InitializationStatus): string {
+  switch (status) {
+    case InitializationStatus.IDLE:
+      return 'Not started'
+    case InitializationStatus.STARTING_WORKLET:
+      return 'Starting worklet...'
+    case InitializationStatus.WORKLET_READY:
+      return 'Worklet ready - can load wallets'
+    case InitializationStatus.ERROR:
+      return 'Worklet error'
+    default:
+      return 'Unknown'
+  }
+}
+
+/**
+ * Get human-readable app status message
+ */
+export function getAppStatusMessage(status: AppStatus): string {
+  switch (status) {
+    case AppStatus.IDLE:
+      return 'Not started'
+    case AppStatus.STARTING_WORKLET:
+      return 'Starting worklet...'
+    case AppStatus.WORKLET_READY:
+      return 'Worklet ready - can load wallets'
+    case AppStatus.LOADING_WALLET:
+      return 'Loading wallet...'
+    case AppStatus.READY:
+      return 'Ready'
+    case AppStatus.ERROR:
+      return 'Error'
+    default:
+      return 'Unknown'
+  }
+}
+
+/**
+ * Gets worklet initialization status from worklet state
+ * 
+ * @param workletState - Worklet state (global, from workletStore)
+ * @returns Worklet initialization status
+ */
+export function getWorkletStatus(
+  workletState: { isWorkletStarted: boolean; isLoading: boolean; error: string | null }
+): InitializationStatus {
+  if (workletState.error) {
+    return InitializationStatus.ERROR
+  }
+
+  if (!workletState.isWorkletStarted) {
+    return workletState.isLoading
+      ? InitializationStatus.STARTING_WORKLET
+      : InitializationStatus.IDLE
+  }
+
+  return InitializationStatus.WORKLET_READY
+}
+
+/**
+ * Derives combined app status from worklet and wallet states
+ * 
+ * This is a convenience function that combines the global worklet state with the 
+ * per-identifier wallet state to produce a unified app-level status.
+ * 
+ * NOTE: This is for convenience only. For granular control, use workletState and 
+ * walletState separately. The combined status hides some information (e.g., can't 
+ * distinguish worklet errors from wallet errors).
+ * 
+ * @param workletState - Worklet state (global, from workletStore)
+ * @param walletState - Wallet state (per-identifier, from wallet state machine)
+ * @returns Combined app status (convenience helper)
+ */
+export function getCombinedStatus(
+  workletState: { isWorkletStarted: boolean; isLoading: boolean; error: string | null },
+  walletState: { type: 'not_loaded' | 'checking' | 'loading' | 'ready' | 'error' }
+): AppStatus {
+  // Worklet errors take precedence
+  if (workletState.error) {
+    return AppStatus.ERROR
+  }
+
+  // Worklet not ready
+  if (!workletState.isWorkletStarted) {
+    return workletState.isLoading
+      ? AppStatus.STARTING_WORKLET
+      : AppStatus.IDLE
+  }
+
+  // Worklet ready, check wallet state
+  switch (walletState.type) {
+    case 'not_loaded':
+      return AppStatus.WORKLET_READY
+    case 'checking':
+    case 'loading':
+      return AppStatus.LOADING_WALLET
+    case 'ready':
+      return AppStatus.READY
+    case 'error':
+      return AppStatus.ERROR
+    default:
+      return AppStatus.IDLE
+  }
+}
+

package/src/utils/jsonUtils.ts

@@ -0,0 +1,75 @@
+/**
+ * JSON Utilities
+ * 
+ * Provides safe JSON stringification and validation utilities
+ * to prevent security issues and ensure data integrity.
+ */
+
+/**
+ * Validate that a value has a safe JSON structure
+ * Prevents prototype pollution and circular references
+ */
+export function validateJSONStructure(value: unknown): boolean {
+  try {
+    // Check for circular references
+    const seen = new WeakSet()
+    
+    function check(value: unknown): boolean {
+      if (value === null || typeof value !== 'object') {
+        return true
+      }
+      
+      if (seen.has(value as object)) {
+        return false // Circular reference
+      }
+      
+      seen.add(value as object)
+      
+      if (Array.isArray(value)) {
+        return value.every(check)
+      }
+      
+      // Check for prototype pollution
+      const proto = Object.getPrototypeOf(value)
+      // Reject objects with non-standard prototypes (not null, Object.prototype, or Array.prototype)
+      // Note: Objects created with Object.create(Array.prototype) should be rejected
+      if (proto !== null && proto !== Object.prototype) {
+        // Allow Array.prototype only for actual arrays (checked above)
+        // Reject objects that inherit from Array.prototype but aren't arrays
+        return false
+      }
+      
+      return Object.values(value as Record<string, unknown>).every(check)
+    }
+    
+    return check(value)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Safe JSON stringify with validation
+ * Validates structure before stringifying to prevent security issues
+ * 
+ * @param value - Value to stringify
+ * @param space - Optional spacing for pretty printing
+ * @returns JSON string
+ * @throws Error if value cannot be safely stringified
+ */
+export function safeStringify(value: unknown, space?: number): string {
+  // Validate structure first
+  if (!validateJSONStructure(value)) {
+    throw new Error('Value contains circular references or unsafe prototype properties')
+  }
+  
+  try {
+    return JSON.stringify(value, null, space)
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Failed to stringify value: ${error.message}`)
+    }
+    throw new Error('Failed to stringify value: Unknown error')
+  }
+}
+

package/src/utils/logger.ts

@@ -0,0 +1,54 @@
+/**
+ * Logger utility for development and production
+ * 
+ * Provides controlled logging that can be disabled in production
+ * to improve performance and prevent information leakage.
+ */
+
+/**
+ * Check if we're in development mode
+ * React Native sets __DEV__ to true in development builds
+ */
+const isDevelopment = typeof __DEV__ !== 'undefined' ? __DEV__ : process.env.NODE_ENV !== 'production'
+
+/**
+ * Log a message (only in development)
+ * 
+ * @param message - Message to log
+ * @param args - Additional arguments to log
+ */
+export function log(...args: unknown[]): void {
+  if (isDevelopment) {
+    console.log(...args)
+  }
+}
+
+/**
+ * Log an error (always logged, but sanitized in production)
+ * 
+ * @param message - Error message
+ * @param error - Error object or additional data
+ */
+export function logError(message: string, error?: unknown): void {
+  if (isDevelopment) {
+    console.error(message, error)
+  } else {
+    // In production, log sanitized errors only
+    // This prevents information leakage while still allowing error tracking
+    console.error(message)
+  }
+}
+
+/**
+ * Log a warning (only in development)
+ * 
+ * @param message - Warning message
+ * @param args - Additional arguments to log
+ */
+export function logWarn(...args: unknown[]): void {
+  if (isDevelopment) {
+    console.warn(...args)
+  }
+}
+
+