@tetherto/wdk-react-native-secure-storage 1.0.0-beta.1 → 1.0.0-beta.3

package/dist/secureStorage.js

@@ -0,0 +1,558 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSecureStorage = createSecureStorage;
+// External packages
+const Keychain = __importStar(require("react-native-keychain"));
+const LocalAuthentication = __importStar(require("expo-local-authentication"));
+// Internal modules
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+const keychainHelpers_1 = require("./keychainHelpers");
+const logger_1 = require("./logger");
+const utils_1 = require("./utils");
+const validation_1 = require("./validation");
+// Secure storage keys (base keys without identifier)
+const ENCRYPTION_KEY = (0, utils_1.createStorageKey)('wallet_encryption_key');
+const ENCRYPTED_SEED = (0, utils_1.createStorageKey)('wallet_encrypted_seed');
+const ENCRYPTED_ENTROPY = (0, utils_1.createStorageKey)('wallet_encrypted_entropy');
+/**
+ * Secure storage wrapper factory for wallet credentials
+ *
+ * Uses react-native-keychain which provides encrypted storage with selective cloud sync.
+ * Creates a new instance each time it's called, allowing different configurations
+ * for different use cases. For most apps, you should create one instance and reuse it.
+ *
+ * SECURITY:
+ * - Storage is app-scoped by the OS (isolated by bundle ID/package name)
+ * - iOS: Uses Keychain Services with iCloud Keychain sync (when user signed into iCloud)
+ * - Android: Uses KeyStore with Google Cloud backup (when device backup enabled)
+ * - Data is ALWAYS encrypted at rest by Keychain (iOS) / KeyStore (Android)
+ * - Cloud sync behavior:
+ *   - Encryption key: ACCESSIBLE.WHEN_UNLOCKED enables iCloud Keychain sync (iOS) and Google Cloud backup (Android)
+ *   - Encrypted seed and entropy: ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY prevents cloud sync (device-only storage)
+ * - Data is encrypted by Apple/Google's E2EE infrastructure
+ * - Encryption key requires device unlock + biometric/PIN authentication to access (when available)
+ * - Encrypted seed and entropy do not require authentication but are still encrypted at rest
+ * - On devices without authentication, data is still encrypted at rest but accessible when device is unlocked
+ * - Device-level keychain/keystore provides rate limiting and lockout mechanisms
+ * - Input validation prevents injection attacks
+ *
+ * Two different apps will NOT share data because storage is isolated by bundle ID/package name.
+ *
+ * @param options - Optional configuration for logger, authentication messages, and timeouts
+ * @returns SecureStorage instance
+ *
+ * @example
+ * ```typescript
+ * const storage = createSecureStorage({
+ *   logger: customLogger,
+ *   authentication: {
+ *     promptMessage: 'Authenticate to access wallet',
+ *   },
+ *   timeoutMs: 30000,
+ * })
+ * ```
+ */
+function createSecureStorage(options) {
+    const logger = options?.logger || logger_1.defaultLogger;
+    const authOptions = options?.authentication || {};
+    // Validate timeout value if provided
+    const requestedTimeout = (0, validation_1.validateTimeout)(options?.timeoutMs);
+    // Validate authentication options if provided
+    (0, validation_1.validateAuthenticationOptions)(authOptions);
+    const timeoutMs = requestedTimeout || constants_1.DEFAULT_TIMEOUT_MS;
+    /**
+     * Error log message generators for consistent error handling
+     */
+    const getErrorLogMessage = (error, operation) => {
+        if (error instanceof errors_1.AuthenticationError) {
+            return `Authentication failed for ${operation}`;
+        }
+        if (error instanceof errors_1.TimeoutError) {
+            return `Timeout during ${operation}`;
+        }
+        if (error instanceof errors_1.ValidationError) {
+            return `Validation error during ${operation}`;
+        }
+        return `Failed to ${operation}`;
+    };
+    /**
+     * Standardized error handling helper
+     *
+     * @param error - The error to handle
+     * @param operation - Name of the operation for logging
+     * @param errorType - The error type to wrap unexpected errors in
+     * @param context - Additional context for logging
+     * @throws The error (either rethrown or wrapped)
+     * @internal
+     */
+    function handleSecureStorageError(error, operation, errorType, context) {
+        if (error instanceof errors_1.SecureStorageError) {
+            const errorContext = error instanceof errors_1.TimeoutError ? { ...context, timeoutMs } : context;
+            logger.error(getErrorLogMessage(error, operation), error, errorContext);
+            throw error;
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        const wrappedError = new errorType(`Unexpected error during ${operation}`, err);
+        logger.error(`Unexpected error during ${operation}`, wrappedError, context);
+        throw wrappedError;
+    }
+    /**
+     * Get the device security level
+     *
+     * @returns The security level: NONE, SECRET (PIN/pattern), or BIOMETRIC
+     * @internal
+     */
+    async function getDeviceSecurityLevel() {
+        try {
+            const securityLevel = await LocalAuthentication.getEnrolledLevelAsync();
+            logger.debug('Device security level', { securityLevel });
+            return securityLevel;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            logger.warn('Failed to check device security level, assuming NONE', { error: err.message });
+            return LocalAuthentication.SecurityLevel.NONE;
+        }
+    }
+    /**
+     * Check if biometric authentication is available
+     */
+    async function checkBiometricAvailable() {
+        try {
+            const compatible = await LocalAuthentication.hasHardwareAsync();
+            const enrolled = await LocalAuthentication.isEnrolledAsync();
+            return compatible && enrolled;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            logger.error('Failed to check biometric availability', err, {});
+            return false;
+        }
+    }
+    /**
+     * Authenticate with biometrics
+     *
+     * @returns true if authentication succeeded, false otherwise
+     */
+    async function performAuthentication() {
+        try {
+            const options = {
+                promptMessage: authOptions.promptMessage || 'Authenticate to access your wallet',
+                cancelLabel: authOptions.cancelLabel || 'Cancel',
+                disableDeviceFallback: authOptions.disableDeviceFallback ?? false,
+            };
+            logger.debug('Starting biometric authentication');
+            const result = await LocalAuthentication.authenticateAsync(options);
+            if (result.success) {
+                logger.info('Biometric authentication successful');
+                return true;
+            }
+            else {
+                logger.warn('Biometric authentication failed or cancelled');
+                return false;
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            const authError = new errors_1.AuthenticationError('Biometric authentication failed', err);
+            logger.error('Biometric authentication error', authError, {});
+            throw authError;
+        }
+    }
+    /**
+     * Generic setter for secure values
+     *
+     * @param baseKey - The base storage key (e.g., ENCRYPTION_KEY)
+     * @param value - The value to store (must be non-empty string, max 10KB)
+     * @param identifier - Optional identifier for multiple wallets
+     * @param requireAuth - Whether authentication should be required (default: true)
+     * @param syncable - Whether the value should sync across devices (default: true)
+     * @throws {ValidationError} If input validation fails
+     * @throws {KeychainWriteError} If keychain operation fails
+     * @throws {TimeoutError} If operation times out
+     * @internal
+     */
+    async function setSecureValue(baseKey, value, identifier, requireAuth = true, syncable = true) {
+        (0, validation_1.validateValue)(value, 'value');
+        (0, validation_1.validateIdentifier)(identifier);
+        try {
+            // Use getEnrolledLevelAsync for more accurate device security detection
+            // This handles the Android case where device might not have any security configured
+            const [securityLevel, storageKey] = await Promise.all([
+                getDeviceSecurityLevel(),
+                (0, utils_1.getStorageKey)(baseKey, identifier),
+            ]);
+            // Device has authentication if security level is not NONE
+            const deviceAuthAvailable = securityLevel !== LocalAuthentication.SecurityLevel.NONE;
+            // If auth was requested but device has no security, log a warning but proceed without auth
+            // Data will still be encrypted at rest by the OS, just not protected by user authentication
+            if (requireAuth && !deviceAuthAvailable) {
+                logger.warn('Device has no security configured. Storing data without authentication protection.', {
+                    baseKey,
+                    identifier,
+                    securityLevel
+                });
+            }
+            logger.debug('Storing secure value', { baseKey, identifier, requireAuth, syncable });
+            const result = await (0, utils_1.withTimeout)(Keychain.setGenericPassword(baseKey, value, {
+                service: storageKey,
+                ...(0, keychainHelpers_1.createKeychainOptions)(deviceAuthAvailable, requireAuth, syncable),
+            }), timeoutMs, `setSecureValue(${baseKey})`);
+            if (result === false) {
+                throw new errors_1.KeychainWriteError(`Failed to store ${baseKey}`);
+            }
+            logger.info('Secure value stored successfully', { baseKey, identifier });
+        }
+        catch (error) {
+            handleSecureStorageError(error, `store ${baseKey}`, errors_1.KeychainWriteError, { identifier, baseKey, requireAuth, syncable });
+        }
+    }
+    /**
+     * Check if a key exists in keychain without reading its value
+     * Used by hasWallet to check existence without authentication
+     *
+     * @param storageKey - The storage key to check
+     * @returns true if key exists with valid password, false if not found
+     * @throws {KeychainReadError} If keychain operation fails (not just "key not found")
+     * @throws {TimeoutError} If operation times out
+     * @internal
+     */
+    async function checkKeyExists(storageKey) {
+        try {
+            const credentials = await (0, utils_1.withTimeout)(Keychain.getGenericPassword({
+                service: storageKey,
+                // NO authenticationPrompt - we're just checking existence
+            }), timeoutMs, `checkKeyExists(${storageKey})`);
+            // Keychain.getGenericPassword returns:
+            // - false when key doesn't exist (not an error, just missing)
+            // - {username, password} object when key exists
+            // - null in some edge cases (treat as not found)
+            return (0, utils_1.isKeychainCredentials)(credentials);
+        }
+        catch (error) {
+            // Any exception here indicates a real keychain failure (not just "key not found")
+            // These should be propagated as errors, not treated as "key doesn't exist"
+            handleSecureStorageError(error, `check key existence (${storageKey})`, errors_1.KeychainReadError, { storageKey });
+        }
+    }
+    /**
+     * Generic getter for secure values
+     *
+     * @param baseKey - The base storage key (e.g., ENCRYPTION_KEY)
+     * @param identifier - Optional identifier for multiple wallets
+     * @param requireAuth - Whether authentication is required (default: true)
+     * @returns The stored value, or null if not found
+     * @throws {ValidationError} If identifier validation fails
+     * @throws {AuthenticationError} If authentication fails (when required and device has security)
+     * @throws {KeychainReadError} If keychain operation fails
+     * @throws {TimeoutError} If operation times out (only for non-auth operations)
+     * @internal
+     */
+    async function getSecureValue(baseKey, identifier, requireAuth = true) {
+        (0, validation_1.validateIdentifier)(identifier);
+        try {
+            // Check device security level to determine if auth is actually possible
+            const [securityLevel, storageKey] = await Promise.all([
+                getDeviceSecurityLevel(),
+                (0, utils_1.getStorageKey)(baseKey, identifier),
+            ]);
+            // Device has authentication if security level is not NONE
+            const deviceAuthAvailable = securityLevel !== LocalAuthentication.SecurityLevel.NONE;
+            // If auth was requested but device has no security, read without auth
+            // Data was stored without auth protection on this device, so we can read it without auth
+            const actuallyRequireAuth = requireAuth && deviceAuthAvailable;
+            if (requireAuth && !deviceAuthAvailable) {
+                logger.warn('Device has no security configured. Reading data without authentication.', {
+                    baseKey,
+                    identifier,
+                    securityLevel
+                });
+            }
+            logger.debug('Retrieving secure value', { baseKey, identifier, requireAuth, actuallyRequireAuth });
+            const keychainOptions = actuallyRequireAuth
+                ? {
+                    service: storageKey,
+                    authenticationPrompt: {
+                        title: authOptions.promptMessage || 'Authenticate to access your wallet',
+                        cancel: authOptions.cancelLabel || 'Cancel',
+                    },
+                }
+                : { service: storageKey };
+            // For auth-required operations (biometrics), don't use timeout.
+            // Biometric authentication should wait indefinitely for user interaction.
+            // Only apply timeout for non-auth operations which should complete quickly.
+            const keychainPromise = Keychain.getGenericPassword(keychainOptions);
+            const credentials = actuallyRequireAuth
+                ? await keychainPromise // No timeout for biometrics - wait for user
+                : await (0, utils_1.withTimeout)(keychainPromise, timeoutMs, `getSecureValue(${baseKey})`);
+            if (!(0, utils_1.isKeychainCredentials)(credentials)) {
+                logger.debug('Secure value not found', { baseKey, identifier });
+                return null;
+            }
+            logger.info('Secure value retrieved successfully', { baseKey, identifier });
+            return credentials.password;
+        }
+        catch (error) {
+            handleSecureStorageError(error, `get ${baseKey}`, errors_1.KeychainReadError, { identifier, baseKey, requireAuth });
+        }
+    }
+    // Create and return the instance
+    return {
+        /**
+         * Check if device security (PIN/pattern/password/biometrics) is enabled
+         *
+         * Apps can use this to check device security status and decide whether to
+         * require users to enable a PIN/pattern/password before storing sensitive data.
+         * The library will function without device security (data is still encrypted at rest).
+         *
+         * @returns Promise resolving to true if device security is enabled, false otherwise
+         */
+        async isDeviceSecurityEnabled() {
+            try {
+                const securityLevel = await LocalAuthentication.getEnrolledLevelAsync();
+                const isEnabled = securityLevel !== LocalAuthentication.SecurityLevel.NONE;
+                logger.debug('Device security check', { securityLevel, isEnabled });
+                return isEnabled;
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                logger.warn('Failed to check device security level', { error: err.message });
+                // If we can't check, assume it's not enabled to be safe
+                return false;
+            }
+        },
+        /**
+         * Check if biometric authentication is available
+         */
+        async isBiometricAvailable() {
+            return checkBiometricAvailable();
+        },
+        /**
+         * Authenticate with biometrics
+         *
+         * @returns true if authentication succeeded, false otherwise
+         */
+        async authenticate() {
+            return performAuthentication();
+        },
+        /**
+         * Store encryption key securely
+         *
+         * @param key - The encryption key to store (must be non-empty string, max 10KB)
+         * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+         * @throws {ValidationError} If key or identifier is invalid
+         * @throws {KeychainWriteError} If keychain operation fails
+         * @throws {TimeoutError} If operation times out
+         */
+        async setEncryptionKey(key, identifier, options) {
+            const requireAuth = options?.requireBiometrics ?? true;
+            return setSecureValue(ENCRYPTION_KEY, key, identifier, requireAuth, true);
+        },
+        /**
+         * Get encryption key from secure storage
+         *
+         * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+         * @returns The encryption key, or null if not found
+         *
+         * @throws {ValidationError} If identifier is invalid format
+         * @throws {AuthenticationError} If authentication fails
+         * @throws {KeychainReadError} If keychain operation fails
+         * @throws {TimeoutError} If operation times out
+         */
+        async getEncryptionKey(identifier, options) {
+            const requireAuth = options?.requireBiometrics ?? true;
+            return getSecureValue(ENCRYPTION_KEY, identifier, requireAuth);
+        },
+        /**
+         * Store encrypted seed securely
+         *
+         * @param encryptedSeed - The encrypted seed to store (must be non-empty string, max 10KB)
+         * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+         *
+         * @throws {ValidationError} If encryptedSeed is invalid
+         * @throws {ValidationError} If identifier is invalid format
+         * @throws {KeychainWriteError} If keychain operation fails
+         * @throws {TimeoutError} If operation times out
+         *
+         * Note: Encrypted seed does not require authentication for access and is stored device-only (not synced across devices)
+         */
+        async setEncryptedSeed(encryptedSeed, identifier) {
+            return setSecureValue(ENCRYPTED_SEED, encryptedSeed, identifier, false, false);
+        },
+        /**
+         * Get encrypted seed from secure storage
+         *
+         * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+         * @returns The encrypted seed, or null if not found
+         *
+         * @throws {ValidationError} If identifier is invalid format
+         * @throws {KeychainReadError} If keychain operation fails
+         * @throws {TimeoutError} If operation times out
+         *
+         * Note: Encrypted seed does not require authentication for access and is stored device-only (not synced across devices)
+         */
+        async getEncryptedSeed(identifier) {
+            return getSecureValue(ENCRYPTED_SEED, identifier, false);
+        },
+        /**
+         * Store encrypted entropy securely
+         *
+         * @param encryptedEntropy - The encrypted entropy to store (must be non-empty string, max 10KB)
+         * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+         *
+         * @throws {ValidationError} If encryptedEntropy is invalid
+         * @throws {ValidationError} If identifier is invalid format
+         * @throws {KeychainWriteError} If keychain operation fails
+         * @throws {TimeoutError} If operation times out
+         *
+         * Note: Encrypted entropy does not require authentication for access and is stored device-only (not synced across devices)
+         */
+        async setEncryptedEntropy(encryptedEntropy, identifier) {
+            return setSecureValue(ENCRYPTED_ENTROPY, encryptedEntropy, identifier, false, false);
+        },
+        /**
+         * Get encrypted entropy from secure storage
+         *
+         * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+         * @returns The encrypted entropy, or null if not found
+         *
+         * @throws {ValidationError} If identifier is invalid format
+         * @throws {KeychainReadError} If keychain operation fails
+         * @throws {TimeoutError} If operation times out
+         *
+         * Note: Encrypted entropy does not require authentication for access and is stored device-only (not synced across devices)
+         */
+        async getEncryptedEntropy(identifier) {
+            return getSecureValue(ENCRYPTED_ENTROPY, identifier, false);
+        },
+        /**
+         * Get all encrypted wallet data at once (seed, entropy, and encryption key)
+         * Uses Promise.all, so fails fast if any operation fails.
+         *
+         * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+         * @returns Object containing seed, entropy, and encryptionKey (may be null if not found)
+         * @throws {ValidationError} If identifier is invalid format
+         * @throws {AuthenticationError} If authentication fails
+         * @throws {KeychainReadError} If keychain operation fails
+         * @throws {TimeoutError} If operation times out
+         */
+        async getAllEncrypted(identifier) {
+            const [encryptedSeed, encryptedEntropy, encryptionKey] = await Promise.all([
+                this.getEncryptedSeed(identifier),
+                this.getEncryptedEntropy(identifier),
+                this.getEncryptionKey(identifier),
+            ]);
+            return {
+                encryptedSeed,
+                encryptedEntropy,
+                encryptionKey,
+            };
+        },
+        /**
+         * Check if wallet credentials exist (without requiring authentication)
+         * Returns false only when wallet is definitively not found. Errors are thrown.
+         *
+         * IMPORTANT: Only checks encrypted seed, NOT encryption key.
+         * Encryption key is protected with biometrics, so checking it would trigger
+         * an authentication prompt. Encrypted seed is stored without auth requirement,
+         * so checking it won't trigger biometrics.
+         *
+         * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+         * @returns true if wallet exists, false if definitively not found
+         * @throws {ValidationError} If identifier is invalid format
+         * @throws {TimeoutError} If operation times out
+         * @throws {KeychainReadError} If keychain operation fails
+         */
+        async hasWallet(identifier) {
+            // ONLY check encrypted seed - it does NOT require biometrics
+            // Encryption key is protected with ACCESS_CONTROL.BIOMETRY_ANY_OR_DEVICE_PASSCODE,
+            // so checking it would trigger a biometric prompt with the default
+            // "Authenticate to retrieve secret" message from react-native-keychain.
+            // By only checking the seed (which is stored without auth requirement),
+            // we can determine wallet existence without triggering biometrics.
+            const seedStorageKey = await (0, utils_1.getStorageKey)(ENCRYPTED_SEED, identifier);
+            return await checkKeyExists(seedStorageKey);
+        },
+        /**
+         * Delete all wallet credentials
+         *
+         * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+         *
+         * @throws {ValidationError} If identifier is invalid format
+         * @throws {SecureStorageError} If deletion fails (with details of which items failed)
+         * @throws {TimeoutError} If operation times out
+         */
+        async deleteWallet(identifier) {
+            // Batch storage key generation
+            const [encryptionKey, encryptedSeed, encryptedEntropy] = await Promise.all([
+                (0, utils_1.getStorageKey)(ENCRYPTION_KEY, identifier),
+                (0, utils_1.getStorageKey)(ENCRYPTED_SEED, identifier),
+                (0, utils_1.getStorageKey)(ENCRYPTED_ENTROPY, identifier),
+            ]);
+            const serviceKeys = [encryptionKey, encryptedSeed, encryptedEntropy];
+            const serviceNames = ['encryptionKey', 'encryptedSeed', 'encryptedEntropy'];
+            logger.debug('Deleting wallet', { identifier, services: serviceNames });
+            const results = await Promise.allSettled(serviceKeys.map((key) => (0, utils_1.withTimeout)(Keychain.resetGenericPassword({ service: key }), timeoutMs, `deleteWallet(${key})`)));
+            const failedServices = serviceNames.filter((_, index) => {
+                const result = results[index];
+                if (!result)
+                    return true;
+                return result.status === 'rejected' || (result.status === 'fulfilled' && result.value === false);
+            });
+            if (failedServices.length > 0) {
+                const error = new errors_1.SecureStorageError(`Failed to delete wallet: ${failedServices.join(', ')}`, 'WALLET_DELETE_ERROR');
+                logger.error('Wallet deletion failed', error, { identifier, failedServices });
+                throw error;
+            }
+            logger.info('Wallet deleted successfully', { identifier });
+        },
+        /**
+         * Cleanup method to release resources associated with this storage instance
+         *
+         * Currently, this is a no-op as the module uses shared resources. This method is provided
+         * for future extensibility and to maintain a consistent API.
+         *
+         * Note: This does NOT delete stored wallet data - use deleteWallet() for that purpose.
+         */
+        cleanup() {
+            // Currently a no-op, but provided for future extensibility
+            // If instance-specific resources are added in the future, they should be
+            // cleaned up here
+            logger.debug('Storage instance cleanup called (no-op)', {});
+        },
+    };
+}

package/dist/utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Type for keychain credentials returned by react-native-keychain
+ */
+export type KeychainCredentials = {
+    username: string;
+    password: string;
+    service: string;
+    storage?: string;
+};
+/**
+ * Type guard to check if a value is valid keychain credentials
+ *
+ * @param value - The value to check
+ * @returns true if value is valid keychain credentials with non-empty password
+ */
+export declare function isKeychainCredentials(value: unknown): value is KeychainCredentials;
+/**
+ * Valid storage key names
+ * These are the only allowed base keys for secure storage
+ */
+export declare const VALID_STORAGE_KEYS: readonly ["wallet_encryption_key", "wallet_encrypted_seed", "wallet_encrypted_entropy"];
+/**
+ * Type-safe storage key names
+ * Union type of valid storage keys
+ */
+export type StorageKey = (typeof VALID_STORAGE_KEYS)[number];
+/**
+ * Create a StorageKey from a string with runtime validation
+ *
+ * @param key - The key string to convert to StorageKey
+ * @returns The validated StorageKey
+ * @throws {ValidationError} If the key is not a valid storage key
+ */
+export declare function createStorageKey(key: string): StorageKey;
+/**
+ * Generate a secure storage key from base key and optional identifier
+ *
+ * @param baseKey - The base storage key (must be a valid StorageKey)
+ * @param identifier - Optional identifier (e.g., email) to support multiple wallets
+ * @returns Promise that resolves to the storage key
+ * @throws {ValidationError} If baseKey is not a valid storage key
+ */
+export declare function getStorageKey(baseKey: StorageKey, identifier?: string): Promise<string>;
+/**
+ * Create a timeout wrapper for promises
+ *
+ * **IMPORTANT:** Uses Promise.race() which does NOT cancel the underlying promise.
+ * The original promise continues executing after timeout (result is ignored).
+ * This is acceptable for keychain operations as they're fast and OS-bounded.
+ *
+ * @param promise - The promise to wrap
+ * @param timeoutMs - Timeout in milliseconds (should be validated via validateTimeout before calling)
+ * @param operation - Name of the operation for error messages
+ * @returns Promise that rejects on timeout
+ * @throws {ValidationError} If timeoutMs is invalid
+ * @throws {TimeoutError} If operation times out
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, operation: string): Promise<T>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAkBlF;AAYD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,yFAIrB,CAAA;AAEV;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAA;AAmB5D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAIxD;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB7F;AAGD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAyBZ"}