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

package/src/utils/mmkvKeyManager.ts

@@ -0,0 +1,256 @@
+/**
+ * MMKV Encryption Key Manager
+ * 
+ * Manages encryption keys for MMKV storage on a per-account basis.
+ * Each account (identified by email/identifier) gets its own encryption key,
+ * allowing multiple accounts on the same device with isolated encrypted storage.
+ * 
+ * SECURITY NOTE: MMKV stores NON-SENSITIVE data only (addresses, balances, metadata).
+ * Since the data is non-sensitive, we use DETERMINISTIC key derivation from account identifier.
+ * This allows the same account to access the same encrypted data across devices.
+ * 
+ * IMPORTANT: For sensitive data (wallet seeds, encryption keys), use SecureStorage which
+ * uses randomly generated keys stored in the device keychain.
+ */
+
+import * as Crypto from 'expo-crypto'
+
+/**
+ * Account identifier type (typically email or user ID)
+ */
+export type AccountIdentifier = string
+
+/**
+ * Convert Uint8Array to base64 string using standard encoding
+ * This implementation follows RFC 4648 and handles all edge cases correctly
+ * 
+ * @param bytes - Uint8Array to convert
+ * @returns Base64 encoded string
+ */
+function bytesToBase64(bytes: Uint8Array): string {
+  // Try to use Buffer if available (common in React Native with polyfills)
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64')
+  }
+  
+  // Fallback to manual encoding for environments without Buffer
+  const base64Chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+  let result = ''
+  
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i] ?? 0
+    const b = i + 1 < bytes.length ? (bytes[i + 1] ?? 0) : 0
+    const c = i + 2 < bytes.length ? (bytes[i + 2] ?? 0) : 0
+    
+    const bitmap = (a << 16) | (b << 8) | c
+    
+    result += base64Chars.charAt((bitmap >> 18) & 63)
+    result += base64Chars.charAt((bitmap >> 12) & 63)
+    
+    if (i + 1 < bytes.length) {
+      result += base64Chars.charAt((bitmap >> 6) & 63)
+    } else {
+      result += '='
+    }
+    
+    if (i + 2 < bytes.length) {
+      result += base64Chars.charAt(bitmap & 63)
+    } else {
+      result += '='
+    }
+  }
+  
+  return result
+}
+
+/**
+ * Maximum number of keys to cache before evicting least recently used
+ * This prevents unbounded memory growth while maintaining performance
+ */
+const MAX_CACHE_SIZE = 100
+
+/**
+ * Cache for derived keys to avoid repeated async operations
+ * Since key derivation is deterministic, we can cache the results
+ * Uses LRU (Least Recently Used) eviction policy to limit memory usage
+ */
+const keyCache = new Map<string, string>()
+const keyAccessOrder = new Map<string, number>()
+let accessCounter = 0
+
+/**
+ * Evict least recently used key from cache when limit is reached
+ */
+function evictLRUKey(): void {
+  if (keyCache.size < MAX_CACHE_SIZE) {
+    return
+  }
+
+  // Find the least recently used key
+  let oldestKey: string | null = null
+  let oldestAccess = Infinity
+
+  for (const [key, accessTime] of keyAccessOrder.entries()) {
+    if (accessTime < oldestAccess) {
+      oldestAccess = accessTime
+      oldestKey = key
+    }
+  }
+
+  // Remove the least recently used key
+  if (oldestKey !== null) {
+    keyCache.delete(oldestKey)
+    keyAccessOrder.delete(oldestKey)
+  }
+}
+
+async function deriveKeyFromAccount(accountIdentifier: AccountIdentifier): Promise<string> {
+  // Check cache first
+  const cachedKey = keyCache.get(accountIdentifier)
+  if (cachedKey !== undefined) {
+    // Update access time for LRU tracking
+    accessCounter++
+    keyAccessOrder.set(accountIdentifier, accessCounter)
+    return cachedKey
+  }
+
+  // Use a constant salt for key derivation
+  // This salt is public and part of the derivation algorithm
+  const SALT = 'wdk-mmkv-encryption-salt-v1'
+  const input = `${SALT}:${accountIdentifier}`
+  
+  // Use expo-crypto for production-grade SHA-256 hashing
+  // This is a well-tested, battle-hardened implementation
+  const hashHex = await Crypto.digestStringAsync(
+    Crypto.CryptoDigestAlgorithm.SHA256,
+    input
+  )
+  
+  // Convert hex string to base64 using standard encoding
+  // SHA-256 produces 64 hex characters (32 bytes)
+  // Convert hex to bytes, then to base64
+  const hexBytes = hashHex.match(/.{1,2}/g)
+  if (!hexBytes || hashHex.length !== 64) {
+    throw new Error(`Invalid SHA-256 hash format: expected 64 hex characters, got ${hashHex.length}`)
+  }
+  const hashBytes = new Uint8Array(
+    hexBytes.map((byte: string) => parseInt(byte, 16))
+  )
+  
+  // Convert bytes to base64 using standard encoding
+  // Use a well-tested base64 encoding implementation
+  const key = bytesToBase64(hashBytes)
+  
+  // Evict LRU key if cache is full
+  evictLRUKey()
+  
+  // Cache the result for future use
+  accessCounter++
+  keyCache.set(accountIdentifier, key)
+  keyAccessOrder.set(accountIdentifier, accessCounter)
+  
+  return key
+}
+
+
+/**
+ * Maximum length for account identifiers to prevent DoS attacks
+ * 256 characters is reasonable for emails and user IDs
+ */
+const MAX_ACCOUNT_IDENTIFIER_LENGTH = 256
+
+/**
+ * Validate account identifier input
+ * 
+ * @param accountIdentifier - Account identifier to validate
+ * @throws Error if validation fails
+ */
+function validateAccountIdentifier(accountIdentifier: AccountIdentifier): void {
+  if (!accountIdentifier || typeof accountIdentifier !== 'string') {
+    throw new Error('Account identifier must be a non-empty string')
+  }
+
+  const trimmed = accountIdentifier.trim()
+  if (trimmed === '') {
+    throw new Error('Account identifier cannot be empty or whitespace only')
+  }
+
+  if (trimmed.length > MAX_ACCOUNT_IDENTIFIER_LENGTH) {
+    throw new Error(`Account identifier exceeds maximum length of ${MAX_ACCOUNT_IDENTIFIER_LENGTH} characters`)
+  }
+
+  // Check for valid UTF-8 encoding (basic check)
+  try {
+    // Ensure the string can be properly encoded
+    encodeURIComponent(trimmed)
+  } catch (error) {
+    throw new Error('Account identifier contains invalid characters')
+  }
+}
+
+/**
+ * Clear the key derivation cache
+ * 
+ * Useful when switching accounts or when you want to free memory.
+ * Note: Keys will be re-derived on next access since derivation is deterministic.
+ * 
+ * @example
+ * ```typescript
+ * // Clear cache when user logs out
+ * clearKeyCache()
+ * ```
+ */
+export function clearKeyCache(): void {
+  keyCache.clear()
+  keyAccessOrder.clear()
+  accessCounter = 0
+}
+
+/**
+ * Get MMKV encryption key for an account
+ * 
+ * SECURITY: Since MMKV stores non-sensitive data, we use deterministic key derivation.
+ * The key is derived from the account identifier, allowing the same account to access
+ * the same encrypted data across devices.
+ * 
+ * The key is NOT stored - it's derived on-demand from the account identifier.
+ * Results are cached since derivation is deterministic.
+ * 
+ * This ensures:
+ * - Account data isolation (different accounts = different keys)
+ * - Cross-device compatibility (same account = same key)
+ * - No key storage needed (deterministic derivation)
+ * 
+ * @param accountIdentifier - Account identifier (email or user ID)
+ * @returns Promise that resolves to encryption key (base64 string, 32 bytes)
+ * @throws Error if account identifier is invalid or key derivation fails
+ * 
+ * @example
+ * ```typescript
+ * const key = await getMMKVKey('user@example.com')
+ * const mmkv = createMMKV({ encryptionKey: key })
+ * ```
+ */
+export async function getMMKVKey(accountIdentifier: AccountIdentifier): Promise<string> {
+  // Validate input before processing
+  validateAccountIdentifier(accountIdentifier)
+
+  // Use trimmed identifier for consistency
+  const trimmedIdentifier = accountIdentifier.trim()
+
+  try {
+    // Derive key deterministically from account identifier
+    // No need to store it - same account identifier always produces same key
+    return await deriveKeyFromAccount(trimmedIdentifier)
+  } catch (error) {
+    // Provide more context in error messages
+    if (error instanceof Error) {
+      throw new Error(`Failed to derive encryption key for account: ${error.message}`)
+    }
+    throw new Error(`Failed to derive encryption key for account: ${String(error)}`)
+  }
+}
+
+
+
+

package/src/utils/mnemonicUtils.ts

@@ -0,0 +1,35 @@
+/**
+ * Mnemonic utility functions
+ */
+
+/**
+ * Validate a mnemonic phrase
+ * 
+ * @param mnemonic - The mnemonic phrase to validate
+ * @returns true if the mnemonic is valid (12 or 24 words, all non-empty)
+ * 
+ * @example
+ * ```ts
+ * validateMnemonic("word1 word2 ... word12") // true
+ * validateMnemonic("word1 word2 ... word24") // true
+ * validateMnemonic("word1 word2") // false (too few words)
+ * ```
+ */
+export function validateMnemonic(mnemonic: string): boolean {
+  const trimmed = mnemonic.trim()
+  
+  // Normalize whitespace first (multiple spaces become single spaces)
+  // This handles cases like "word1  word2" where multiple spaces should be normalized
+  const normalized = trimmed.replace(/\s+/g, ' ')
+  
+  // Split and validate
+  const words = normalized.split(' ')
+  const validLengths = [12, 24]
+  
+  // Check word count and that all words are non-empty
+  return validLengths.includes(words.length) && words.every(word => word.length > 0)
+}
+
+
+
+

package/src/utils/operationMutex.ts

@@ -0,0 +1,181 @@
+/**
+ * Operation Mutex - Prevents concurrent wallet operations
+ * 
+ * This utility provides a mutex/lock mechanism to ensure only one wallet operation
+ * can execute at a time, preventing race conditions and state corruption.
+ */
+
+import { getWalletStore } from '../store/walletStore'
+import { log, logWarn } from './logger'
+
+/**
+ * Operation mutex result
+ */
+export interface MutexResult {
+  /** Whether the operation was acquired */
+  acquired: boolean
+  /** Current operation description if mutex is held */
+  currentOperation: string | null
+  /** Release function to call when operation completes */
+  release: () => void
+}
+
+/**
+ * Try to acquire operation mutex
+ * 
+ * @param operationDescription - Description of the operation (for debugging)
+ * @returns MutexResult with acquired status and release function
+ * 
+ * @example
+ * ```typescript
+ * const mutex = acquireOperationMutex('switchWallet')
+ * if (!mutex.acquired) {
+ *   throw new Error(`Operation in progress: ${mutex.currentOperation}`)
+ * }
+ * try {
+ *   // Perform operation
+ * } finally {
+ *   mutex.release()
+ * }
+ * ```
+ */
+export function acquireOperationMutex(operationDescription: string): MutexResult {
+  const walletStore = getWalletStore()
+  const state = walletStore.getState()
+  
+  // Check if operation is already in progress
+  if (state.isOperationInProgress) {
+    logWarn(`[OperationMutex] Operation "${operationDescription}" blocked by: ${state.currentOperation}`)
+    return {
+      acquired: false,
+      currentOperation: state.currentOperation,
+      release: () => {}, // No-op release
+    }
+  }
+  
+  // Acquire mutex
+  walletStore.setState({
+    isOperationInProgress: true,
+    currentOperation: operationDescription,
+  })
+  
+  log(`[OperationMutex] Acquired mutex for: ${operationDescription}`)
+  
+  // Return release function
+  return {
+    acquired: true,
+    currentOperation: null,
+    release: () => {
+      const currentState = walletStore.getState()
+      // Only release if we're still the current operation
+      if (currentState.currentOperation === operationDescription) {
+        walletStore.setState({
+          isOperationInProgress: false,
+          currentOperation: null,
+        })
+        log(`[OperationMutex] Released mutex for: ${operationDescription}`)
+      } else {
+        logWarn(`[OperationMutex] Attempted to release mutex for "${operationDescription}" but current operation is "${currentState.currentOperation}"`)
+      }
+    },
+  }
+}
+
+/**
+ * Default timeout for operations (30 seconds)
+ * Operations that exceed this timeout will be automatically released
+ */
+const DEFAULT_OPERATION_TIMEOUT_MS = 30 * 1000
+
+/**
+ * Execute an operation with mutex protection
+ * Automatically acquires and releases mutex
+ * Includes timeout protection to prevent stuck operations
+ * 
+ * @param operationDescription - Description of the operation
+ * @param operation - Async operation to execute
+ * @param timeoutMs - Optional timeout in milliseconds (default: 30000ms / 30 seconds)
+ * @returns Promise with operation result
+ * @throws Error if mutex cannot be acquired, operation fails, or timeout is exceeded
+ * 
+ * @example
+ * ```typescript
+ * await withOperationMutex('switchWallet', async () => {
+ *   await WalletSwitchingService.switchToWallet(walletId)
+ * })
+ * 
+ * // With custom timeout
+ * await withOperationMutex('longOperation', async () => {
+ *   await longRunningOperation()
+ * }, 60000) // 60 second timeout
+ * ```
+ */
+export async function withOperationMutex<T>(
+  operationDescription: string,
+  operation: () => Promise<T>,
+  timeoutMs: number = DEFAULT_OPERATION_TIMEOUT_MS
+): Promise<T> {
+  const mutex = acquireOperationMutex(operationDescription)
+  
+  if (!mutex.acquired) {
+    throw new Error(
+      `Cannot execute "${operationDescription}": Another operation is in progress (${mutex.currentOperation})`
+    )
+  }
+  
+  // Set up timeout protection
+  let timeoutId: NodeJS.Timeout | null = null
+  let timeoutExceeded = false
+  
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      timeoutExceeded = true
+      logWarn(`[OperationMutex] Operation "${operationDescription}" exceeded timeout of ${timeoutMs}ms`)
+      mutex.release()
+      reject(new Error(
+        `Operation "${operationDescription}" exceeded timeout of ${timeoutMs}ms`
+      ))
+    }, timeoutMs)
+  })
+  
+  try {
+    // Race between operation and timeout
+    return await Promise.race([
+      operation(),
+      timeoutPromise,
+    ])
+  } catch (error) {
+    // If timeout occurred, error is already handled
+    if (timeoutExceeded) {
+      throw error
+    }
+    // Otherwise, re-throw the operation error
+    throw error
+  } finally {
+    // Clear timeout if operation completed before timeout
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
+    // Only release if timeout didn't already release it
+    if (!timeoutExceeded) {
+      mutex.release()
+    }
+  }
+}
+
+/**
+ * Check if an operation is currently in progress
+ */
+export function isOperationInProgress(): boolean {
+  const walletStore = getWalletStore()
+  return walletStore.getState().isOperationInProgress
+}
+
+/**
+ * Get current operation description
+ */
+export function getCurrentOperation(): string | null {
+  const walletStore = getWalletStore()
+  return walletStore.getState().currentOperation
+}
+

package/src/utils/result.ts

@@ -0,0 +1,57 @@
+/**
+ * Result Type for Error Handling
+ * 
+ * Provides a consistent pattern for handling operations that can succeed or fail.
+ * This eliminates the need for try-catch blocks and provides type-safe error handling.
+ */
+
+/**
+ * Result type representing success or failure
+ */
+export type Result<T, E = Error> =
+  | { success: true; data: T; error?: never }
+  | { success: false; error: E; data?: never }
+
+/**
+ * Create a success result
+ */
+export function ok<T>(data: T): Result<T, never> {
+  return { success: true, data }
+}
+
+/**
+ * Create an error result
+ */
+export function err<E>(error: E): Result<never, E> {
+  return { success: false, error }
+}
+
+/**
+ * Wrap an async function to return a Result instead of throwing
+ */
+export async function toResult<T, E = Error>(
+  fn: () => Promise<T>
+): Promise<Result<T, E>> {
+  try {
+    const data = await fn()
+    return ok(data)
+  } catch (error) {
+    return err(error as E)
+  }
+}
+
+/**
+ * Wrap a synchronous function to return a Result instead of throwing
+ */
+export function toResultSync<T, E = Error>(
+  fn: () => T
+): Result<T, E> {
+  try {
+    const data = fn()
+    return ok(data)
+  } catch (error) {
+    return err(error as E)
+  }
+}
+
+