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

package/dist/utils.js

@@ -0,0 +1,170 @@
+"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.VALID_STORAGE_KEYS = void 0;
+exports.isKeychainCredentials = isKeychainCredentials;
+exports.createStorageKey = createStorageKey;
+exports.getStorageKey = getStorageKey;
+exports.withTimeout = withTimeout;
+// External packages
+const Crypto = __importStar(require("expo-crypto"));
+// Internal modules
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+const validation_1 = require("./validation");
+/**
+ * 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
+ */
+function isKeychainCredentials(value) {
+    if (value === false ||
+        value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value)) {
+        return false;
+    }
+    const obj = value;
+    return (typeof obj.password === 'string' &&
+        obj.password.length > 0 &&
+        typeof obj.username === 'string' &&
+        typeof obj.service === 'string' &&
+        (obj.storage === undefined || typeof obj.storage === 'string'));
+}
+/**
+ * Hash identifier using SHA-256 from expo-crypto
+ *
+ * @param str - Input string to hash
+ * @returns Promise that resolves to a 64-character hexadecimal SHA-256 hash
+ */
+async function hashIdentifier(str) {
+    return Crypto.digestStringAsync(Crypto.CryptoDigestAlgorithm.SHA256, str);
+}
+/**
+ * Valid storage key names
+ * These are the only allowed base keys for secure storage
+ */
+exports.VALID_STORAGE_KEYS = [
+    'wallet_encryption_key',
+    'wallet_encrypted_seed',
+    'wallet_encrypted_entropy',
+];
+/**
+ * Runtime validation for storage keys
+ * Ensures only valid base keys are used at runtime
+ *
+ * @param key - The key to validate
+ * @throws {ValidationError} If the key is not a valid storage key
+ * @internal
+ */
+function assertValidStorageKey(key) {
+    const validKey = exports.VALID_STORAGE_KEYS.find((k) => k === key);
+    if (!validKey) {
+        throw new errors_1.ValidationError(`Invalid storage key: ${key}. Valid keys are: ${exports.VALID_STORAGE_KEYS.join(', ')}`);
+    }
+}
+/**
+ * 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
+ */
+function createStorageKey(key) {
+    assertValidStorageKey(key);
+    // After validation, we know key is one of VALID_STORAGE_KEYS
+    return key;
+}
+/**
+ * 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
+ */
+async function getStorageKey(baseKey, identifier) {
+    // Runtime validation for type system bypasses (e.g., 'invalid_key' as any)
+    assertValidStorageKey(baseKey);
+    // Handle undefined/null early
+    if (identifier == null) {
+        return baseKey;
+    }
+    // Validate identifier first (this will throw for empty strings and invalid formats)
+    (0, validation_1.validateIdentifier)(identifier);
+    // Normalize: lowercase and trim (validation ensures it's not empty after trim)
+    const normalized = identifier.toLowerCase().trim();
+    // Use SHA-256 hash from expo-crypto to prevent collisions and ensure safe key format
+    // This is a battle-tested, production-ready solution
+    const hash = await hashIdentifier(normalized);
+    return `${baseKey}_${hash}`;
+}
+/**
+ * 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
+ */
+async function withTimeout(promise, timeoutMs, operation) {
+    // Note: validateTimeout should be called before this function to ensure timeoutMs is valid.
+    // This function only performs basic safety checks for direct calls.
+    if (typeof timeoutMs !== 'number' || !isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new errors_1.ValidationError(`Invalid timeout value: ${timeoutMs}. Must be a positive finite number.`);
+    }
+    if (timeoutMs < constants_1.MIN_TIMEOUT_MS || timeoutMs > constants_1.MAX_TIMEOUT_MS) {
+        throw new errors_1.ValidationError(`Timeout ${timeoutMs}ms is out of range. Must be between ${constants_1.MIN_TIMEOUT_MS}ms and ${constants_1.MAX_TIMEOUT_MS}ms.`);
+    }
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            reject(new errors_1.TimeoutError(`Operation ${operation} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/validation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Authentication options for biometric prompts
+ */
+interface AuthenticationOptions {
+    promptMessage?: string;
+    cancelLabel?: string;
+    disableDeviceFallback?: boolean;
+}
+/**
+ * Maximum length for identifier strings
+ */
+export declare const MAX_IDENTIFIER_LENGTH = 256;
+/**
+ * Maximum length for stored values (10KB)
+ */
+export declare const MAX_VALUE_LENGTH = 10240;
+/**
+ * Validates an identifier parameter
+ *
+ * @param identifier - The identifier to validate (optional)
+ * @throws {ValidationError} If identifier is invalid
+ */
+export declare function validateIdentifier(identifier?: string): void;
+/**
+ * Validates a value to be stored
+ *
+ * @param value - The value to validate
+ * @param fieldName - Name of the field for error messages
+ * @throws {ValidationError} If value is invalid
+ */
+export declare function validateValue(value: string, fieldName?: string): void;
+/**
+ * Validates a timeout value
+ *
+ * @param timeoutMs - The timeout value to validate (optional)
+ * @returns The validated timeout value, or undefined if not provided
+ * @throws {ValidationError} If timeout is invalid
+ */
+export declare function validateTimeout(timeoutMs: number | undefined): number | undefined;
+/**
+ * Validates authentication options
+ *
+ * @param options - The authentication options to validate (optional)
+ * @throws {ValidationError} If any option is invalid
+ */
+export declare function validateAuthenticationOptions(options?: AuthenticationOptions): void;
+export {};
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,UAAU,qBAAqB;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAA;AAExC;;GAEG;AACH,eAAO,MAAM,gBAAgB,QAAQ,CAAA;AAiBrC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAyB5D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAgB,GAAG,IAAI,CAkB9E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAkBjF;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI,CA4BnF"}

package/dist/validation.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_VALUE_LENGTH = exports.MAX_IDENTIFIER_LENGTH = void 0;
+exports.validateIdentifier = validateIdentifier;
+exports.validateValue = validateValue;
+exports.validateTimeout = validateTimeout;
+exports.validateAuthenticationOptions = validateAuthenticationOptions;
+const errors_1 = require("./errors");
+const constants_1 = require("./constants");
+/**
+ * Maximum length for identifier strings
+ */
+exports.MAX_IDENTIFIER_LENGTH = 256;
+/**
+ * Maximum length for stored values (10KB)
+ */
+exports.MAX_VALUE_LENGTH = 10240;
+/**
+ * Pattern for valid identifiers
+ * Allows: alphanumeric, dots, dashes, underscores, plus signs, and optional email-like format
+ *
+ * Examples of valid identifiers:
+ * - "user123" (simple identifier)
+ * - "my_wallet" (with underscore)
+ * - "test-identifier" (with dash)
+ * - "user@example.com" (email format)
+ * - "user+tag@example.com" (email with plus sign in local part)
+ *
+ * The email part (after @) is optional - simple identifiers are fully supported.
+ */
+const IDENTIFIER_PATTERN = /^[a-zA-Z0-9._+-]+(@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})?$/;
+/**
+ * Validates an identifier parameter
+ *
+ * @param identifier - The identifier to validate (optional)
+ * @throws {ValidationError} If identifier is invalid
+ */
+function validateIdentifier(identifier) {
+    if (identifier === undefined || identifier === null) {
+        return; // Optional parameter is allowed
+    }
+    if (typeof identifier !== 'string') {
+        throw new errors_1.ValidationError('Identifier must be a string');
+    }
+    const trimmed = identifier.trim();
+    if (trimmed === '') {
+        throw new errors_1.ValidationError('Identifier cannot be empty');
+    }
+    if (trimmed.length > exports.MAX_IDENTIFIER_LENGTH) {
+        throw new errors_1.ValidationError(`Identifier exceeds maximum length of ${exports.MAX_IDENTIFIER_LENGTH} characters`);
+    }
+    if (!IDENTIFIER_PATTERN.test(trimmed)) {
+        throw new errors_1.ValidationError('Identifier contains invalid characters. Allowed: alphanumeric, dots, dashes, underscores, plus signs, and email format');
+    }
+}
+/**
+ * Validates a value to be stored
+ *
+ * @param value - The value to validate
+ * @param fieldName - Name of the field for error messages
+ * @throws {ValidationError} If value is invalid
+ */
+function validateValue(value, fieldName = 'value') {
+    if (value === null || value === undefined) {
+        throw new errors_1.ValidationError(`${fieldName} cannot be null or undefined`);
+    }
+    if (typeof value !== 'string') {
+        throw new errors_1.ValidationError(`${fieldName} must be a string`);
+    }
+    if (value.length === 0) {
+        throw new errors_1.ValidationError(`${fieldName} cannot be empty`);
+    }
+    if (value.length > exports.MAX_VALUE_LENGTH) {
+        throw new errors_1.ValidationError(`${fieldName} exceeds maximum length of ${exports.MAX_VALUE_LENGTH} characters`);
+    }
+}
+/**
+ * Validates a timeout value
+ *
+ * @param timeoutMs - The timeout value to validate (optional)
+ * @returns The validated timeout value, or undefined if not provided
+ * @throws {ValidationError} If timeout is invalid
+ */
+function validateTimeout(timeoutMs) {
+    if (timeoutMs === undefined) {
+        return undefined;
+    }
+    if (typeof timeoutMs !== 'number' || isNaN(timeoutMs) || !isFinite(timeoutMs)) {
+        throw new errors_1.ValidationError(`Invalid timeout value: ${timeoutMs}. Must be a finite number.`);
+    }
+    if (timeoutMs < constants_1.MIN_TIMEOUT_MS) {
+        throw new errors_1.ValidationError(`Timeout ${timeoutMs}ms is too short. Minimum is ${constants_1.MIN_TIMEOUT_MS}ms.`);
+    }
+    if (timeoutMs > constants_1.MAX_TIMEOUT_MS) {
+        throw new errors_1.ValidationError(`Timeout ${timeoutMs}ms is too long. Maximum is ${constants_1.MAX_TIMEOUT_MS}ms.`);
+    }
+    return timeoutMs;
+}
+/**
+ * Validates authentication options
+ *
+ * @param options - The authentication options to validate (optional)
+ * @throws {ValidationError} If any option is invalid
+ */
+function validateAuthenticationOptions(options) {
+    if (!options) {
+        return;
+    }
+    if (options.promptMessage !== undefined) {
+        if (typeof options.promptMessage !== 'string') {
+            throw new errors_1.ValidationError('Authentication promptMessage must be a string');
+        }
+        if (options.promptMessage.trim().length === 0) {
+            throw new errors_1.ValidationError('Authentication promptMessage cannot be empty');
+        }
+    }
+    if (options.cancelLabel !== undefined) {
+        if (typeof options.cancelLabel !== 'string') {
+            throw new errors_1.ValidationError('Authentication cancelLabel must be a string');
+        }
+        if (options.cancelLabel.trim().length === 0) {
+            throw new errors_1.ValidationError('Authentication cancelLabel cannot be empty');
+        }
+    }
+    if (options.disableDeviceFallback !== undefined) {
+        if (typeof options.disableDeviceFallback !== 'boolean') {
+            throw new errors_1.ValidationError('Authentication disableDeviceFallback must be a boolean');
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tetherto/wdk-react-native-secure-storage",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Secure storage abstractions for React Native - provides secure storage for sensitive data (encrypted seeds, keys) using react-native-keychain",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",