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

package/dist/utils/errorUtils.js

@@ -0,0 +1,264 @@
+/**
+ * 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 var SanitizationLevel;
+(function (SanitizationLevel) {
+    SanitizationLevel["NONE"] = "none";
+    SanitizationLevel["DEVELOPMENT"] = "dev";
+    SanitizationLevel["PRODUCTION"] = "prod";
+})(SanitizationLevel || (SanitizationLevel = {}));
+/**
+ * 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) {
+    return SAFE_PATTERNS.some(pattern => pattern.test(text));
+}
+/**
+ * Mask sensitive string patterns (hex/base64) for development mode
+ */
+function maskSensitiveStrings(message) {
+    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) {
+    return message
+        .replace(/file:\/\/[^\s]+/gi, '[file path]')
+        .replace(/\/[^\s]+\/[^\s]+/g, '[path]');
+}
+/**
+ * Get replacement text for a sensitive pattern match
+ */
+function getSensitiveReplacement(match) {
+    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) {
+    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, isDevelopment = false, context) {
+    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, sanitizeLevel = process.env.NODE_ENV === 'production'
+    ? SanitizationLevel.PRODUCTION
+    : SanitizationLevel.DEVELOPMENT, context) {
+    let errorMessage;
+    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) {
+    return normalizeError(error).message;
+}
+/**
+ * Check if error is a specific type
+ */
+export function isErrorType(error, typeName) {
+    return error instanceof Error && error.name === typeName;
+}
+/**
+ * Create a standardized error with context
+ */
+export function createContextualError(message, context) {
+    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) {
+    // 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;
+}
+//# sourceMappingURL=errorUtils.js.map

package/dist/utils/errorUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorUtils.js","sourceRoot":"","sources":["../../src/utils/errorUtils.ts"],"names":[],"mappings":"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"}

package/dist/utils/initializationState.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 declare 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 declare 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 declare function isErrorStatus(status: InitializationStatus): boolean;
+/**
+ * Helper to check if worklet initialization is complete and ready
+ */
+export declare function isReadyStatus(status: InitializationStatus): boolean;
+/**
+ * Helper to check if worklet initialization is in progress
+ */
+export declare function isInProgressStatus(status: InitializationStatus): boolean;
+/**
+ * Helper to check if app status represents an in-progress state
+ */
+export declare function isAppInProgressStatus(status: AppStatus): boolean;
+/**
+ * Helper to check if app is ready (worklet + wallet both ready)
+ */
+export declare function isAppReadyStatus(status: AppStatus): boolean;
+/**
+ * Helper to check if worklet has started (worklet runtime is ready)
+ * Once worklet is ready, you can load wallets (per identifier)
+ */
+export declare function hasWorkletStarted(status: InitializationStatus): boolean;
+/**
+ * Helper to check if wallet operations can be performed
+ * Returns true when worklet is ready (wallets can be loaded per identifier)
+ */
+export declare function canLoadWallet(status: InitializationStatus): boolean;
+/**
+ * Helper to check if app status indicates worklet has started
+ */
+export declare function hasWorkletStartedApp(status: AppStatus): boolean;
+/**
+ * Helper to check if wallet operations can be performed based on app status
+ */
+export declare function canLoadWalletApp(status: AppStatus): boolean;
+/**
+ * Get human-readable worklet initialization status message
+ */
+export declare function getStatusMessage(status: InitializationStatus): string;
+/**
+ * Get human-readable app status message
+ */
+export declare function getAppStatusMessage(status: AppStatus): string;
+/**
+ * Gets worklet initialization status from worklet state
+ *
+ * @param workletState - Worklet state (global, from workletStore)
+ * @returns Worklet initialization status
+ */
+export declare function getWorkletStatus(workletState: {
+    isWorkletStarted: boolean;
+    isLoading: boolean;
+    error: string | null;
+}): InitializationStatus;
+/**
+ * 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 declare function getCombinedStatus(workletState: {
+    isWorkletStarted: boolean;
+    isLoading: boolean;
+    error: string | null;
+}, walletState: {
+    type: 'not_loaded' | 'checking' | 'loading' | 'ready' | 'error';
+}): AppStatus;

package/dist/utils/initializationState.js

@@ -0,0 +1,220 @@
+/**
+ * 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 var InitializationStatus;
+(function (InitializationStatus) {
+    /** Initial state - worklet not started */
+    InitializationStatus["IDLE"] = "idle";
+    /** Worklet runtime is starting (happens once, global) */
+    InitializationStatus["STARTING_WORKLET"] = "starting_worklet";
+    /** Worklet is ready - can now load wallets (per identifier) */
+    InitializationStatus["WORKLET_READY"] = "worklet_ready";
+    /** Error state - worklet initialization failed */
+    InitializationStatus["ERROR"] = "error";
+})(InitializationStatus || (InitializationStatus = {}));
+/**
+ * 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 var AppStatus;
+(function (AppStatus) {
+    /** Worklet not started */
+    AppStatus["IDLE"] = "idle";
+    /** Worklet is starting */
+    AppStatus["STARTING_WORKLET"] = "starting_worklet";
+    /** Worklet ready, no wallet loaded */
+    AppStatus["WORKLET_READY"] = "worklet_ready";
+    /** Loading a wallet (checking existence, decrypting, initializing) */
+    AppStatus["LOADING_WALLET"] = "loading_wallet";
+    /** Fully ready - worklet started, wallet loaded, addresses available */
+    AppStatus["READY"] = "ready";
+    /** Error state - worklet or wallet error */
+    AppStatus["ERROR"] = "error";
+})(AppStatus || (AppStatus = {}));
+/**
+ * Helper to check if status represents an error state
+ */
+export function isErrorStatus(status) {
+    return status === InitializationStatus.ERROR;
+}
+/**
+ * Helper to check if worklet initialization is complete and ready
+ */
+export function isReadyStatus(status) {
+    return status === InitializationStatus.WORKLET_READY;
+}
+/**
+ * Helper to check if worklet initialization is in progress
+ */
+export function isInProgressStatus(status) {
+    return status === InitializationStatus.STARTING_WORKLET;
+}
+/**
+ * Helper to check if app status represents an in-progress state
+ */
+export function isAppInProgressStatus(status) {
+    return [
+        AppStatus.STARTING_WORKLET,
+        AppStatus.LOADING_WALLET,
+    ].includes(status);
+}
+/**
+ * Helper to check if app is ready (worklet + wallet both ready)
+ */
+export function isAppReadyStatus(status) {
+    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) {
+    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) {
+    return status === InitializationStatus.WORKLET_READY;
+}
+/**
+ * Helper to check if app status indicates worklet has started
+ */
+export function hasWorkletStartedApp(status) {
+    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) {
+    return [
+        AppStatus.WORKLET_READY,
+        AppStatus.LOADING_WALLET,
+        AppStatus.READY,
+    ].includes(status);
+}
+/**
+ * Get human-readable worklet initialization status message
+ */
+export function getStatusMessage(status) {
+    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) {
+    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) {
+    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, walletState) {
+    // 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;
+    }
+}
+//# sourceMappingURL=initializationState.js.map

package/dist/utils/initializationState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initializationState.js","sourceRoot":"","sources":["../../src/utils/initializationState.ts"],"names":[],"mappings":"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"}

package/dist/utils/jsonUtils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare function validateJSONStructure(value: unknown): boolean;
+/**
+ * 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 declare function safeStringify(value: unknown, space?: number): string;