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

package/src/utils.ts

@@ -0,0 +1,176 @@
+// External packages
+import * as Crypto from 'expo-crypto'
+
+// Internal modules
+import { MIN_TIMEOUT_MS, MAX_TIMEOUT_MS } from './constants'
+import { TimeoutError, ValidationError } from './errors'
+import { validateIdentifier } from './validation'
+
+/**
+ * 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 function isKeychainCredentials(value: unknown): value is KeychainCredentials {
+  if (
+    value === false ||
+    value === null ||
+    typeof value !== 'object' ||
+    Array.isArray(value)
+  ) {
+    return false
+  }
+
+  const obj = value as Record<string, unknown>
+  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: string): Promise<string> {
+  return Crypto.digestStringAsync(Crypto.CryptoDigestAlgorithm.SHA256, str)
+}
+
+/**
+ * Valid storage key names
+ * These are the only allowed base keys for secure storage
+ */
+export const VALID_STORAGE_KEYS = [
+  'wallet_encryption_key',
+  'wallet_encrypted_seed',
+  'wallet_encrypted_entropy',
+] as const
+
+/**
+ * Type-safe storage key names
+ * Union type of valid storage keys
+ */
+export type StorageKey = (typeof VALID_STORAGE_KEYS)[number]
+
+/**
+ * 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: string): asserts key is StorageKey {
+  const validKey = VALID_STORAGE_KEYS.find((k) => k === key)
+  if (!validKey) {
+    throw new ValidationError(
+      `Invalid storage key: ${key}. Valid keys are: ${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
+ */
+export function createStorageKey(key: string): StorageKey {
+  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
+ */
+export async function getStorageKey(baseKey: StorageKey, identifier?: string): Promise<string> {
+  // 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)
+  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
+ */
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  operation: string
+): Promise<T> {
+  // 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 ValidationError(`Invalid timeout value: ${timeoutMs}. Must be a positive finite number.`)
+  }
+  
+  if (timeoutMs < MIN_TIMEOUT_MS || timeoutMs > MAX_TIMEOUT_MS) {
+    throw new ValidationError(
+      `Timeout ${timeoutMs}ms is out of range. Must be between ${MIN_TIMEOUT_MS}ms and ${MAX_TIMEOUT_MS}ms.`
+    )
+  }
+  
+  let timeout
+  const timeoutPromise = new Promise<T>((_, reject) => {
+    timeout = setTimeout(() => {
+      reject(new TimeoutError(`Operation ${operation} timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+  })
+  
+  try {
+    return await Promise.race([promise, timeoutPromise])
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+

package/src/validation.ts

@@ -0,0 +1,160 @@
+import { ValidationError } from './errors'
+import { MIN_TIMEOUT_MS, MAX_TIMEOUT_MS } from './constants'
+
+/**
+ * Authentication options for biometric prompts
+ */
+interface AuthenticationOptions {
+  promptMessage?: string
+  cancelLabel?: string
+  disableDeviceFallback?: boolean
+}
+
+/**
+ * Maximum length for identifier strings
+ */
+export const MAX_IDENTIFIER_LENGTH = 256
+
+/**
+ * Maximum length for stored values (10KB)
+ */
+export const 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
+ */
+export function validateIdentifier(identifier?: string): void {
+  if (identifier === undefined || identifier === null) {
+    return // Optional parameter is allowed
+  }
+
+  if (typeof identifier !== 'string') {
+    throw new ValidationError('Identifier must be a string')
+  }
+
+  const trimmed = identifier.trim()
+  if (trimmed === '') {
+    throw new ValidationError('Identifier cannot be empty')
+  }
+
+  if (trimmed.length > MAX_IDENTIFIER_LENGTH) {
+    throw new ValidationError(
+      `Identifier exceeds maximum length of ${MAX_IDENTIFIER_LENGTH} characters`
+    )
+  }
+
+  if (!IDENTIFIER_PATTERN.test(trimmed)) {
+    throw new 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
+ */
+export function validateValue(value: string, fieldName: string = 'value'): void {
+  if (value === null || value === undefined) {
+    throw new ValidationError(`${fieldName} cannot be null or undefined`)
+  }
+
+  if (typeof value !== 'string') {
+    throw new ValidationError(`${fieldName} must be a string`)
+  }
+
+  if (value.length === 0) {
+    throw new ValidationError(`${fieldName} cannot be empty`)
+  }
+
+  if (value.length > MAX_VALUE_LENGTH) {
+    throw new ValidationError(
+      `${fieldName} exceeds maximum length of ${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
+ */
+export function validateTimeout(timeoutMs: number | undefined): number | undefined {
+  if (timeoutMs === undefined) {
+    return undefined
+  }
+
+  if (typeof timeoutMs !== 'number' || isNaN(timeoutMs) || !isFinite(timeoutMs)) {
+    throw new ValidationError(`Invalid timeout value: ${timeoutMs}. Must be a finite number.`)
+  }
+
+  if (timeoutMs < MIN_TIMEOUT_MS) {
+    throw new ValidationError(`Timeout ${timeoutMs}ms is too short. Minimum is ${MIN_TIMEOUT_MS}ms.`)
+  }
+
+  if (timeoutMs > MAX_TIMEOUT_MS) {
+    throw new ValidationError(`Timeout ${timeoutMs}ms is too long. Maximum is ${MAX_TIMEOUT_MS}ms.`)
+  }
+
+  return timeoutMs
+}
+
+/**
+ * Validates authentication options
+ * 
+ * @param options - The authentication options to validate (optional)
+ * @throws {ValidationError} If any option is invalid
+ */
+export function validateAuthenticationOptions(options?: AuthenticationOptions): void {
+  if (!options) {
+    return
+  }
+
+  if (options.promptMessage !== undefined) {
+    if (typeof options.promptMessage !== 'string') {
+      throw new ValidationError('Authentication promptMessage must be a string')
+    }
+    if (options.promptMessage.trim().length === 0) {
+      throw new ValidationError('Authentication promptMessage cannot be empty')
+    }
+  }
+
+  if (options.cancelLabel !== undefined) {
+    if (typeof options.cancelLabel !== 'string') {
+      throw new ValidationError('Authentication cancelLabel must be a string')
+    }
+    if (options.cancelLabel.trim().length === 0) {
+      throw new ValidationError('Authentication cancelLabel cannot be empty')
+    }
+  }
+
+  if (options.disableDeviceFallback !== undefined) {
+    if (typeof options.disableDeviceFallback !== 'boolean') {
+      throw new ValidationError('Authentication disableDeviceFallback must be a boolean')
+    }
+  }
+}
+

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/__tests__", "**/*.test.ts", "**/*.spec.ts"]
+}
+