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

package/src/__tests__/utils.test.ts

@@ -0,0 +1,182 @@
+import { 
+  getStorageKey, 
+  withTimeout,
+  isKeychainCredentials,
+  createStorageKey,
+} from '../utils'
+import { MIN_TIMEOUT_MS, MAX_TIMEOUT_MS } from '../constants'
+import { TimeoutError, ValidationError } from '../errors'
+
+// Mock expo-crypto
+jest.mock('expo-crypto', () => ({
+  CryptoDigestAlgorithm: {
+    SHA256: 'SHA256',
+  },
+  digestStringAsync: jest.fn(async (_algorithm: string, data: string) => {
+    // Simple deterministic hash for testing
+    let hash = 0
+    for (let i = 0; i < data.length; i++) {
+      const char = data.charCodeAt(i)
+      hash = ((hash << 5) - hash) + char
+      hash = hash & hash
+    }
+    const hex = Math.abs(hash).toString(16).padStart(8, '0')
+    return (hex.repeat(8)).substring(0, 64)
+  }),
+}))
+
+describe('utils', () => {
+
+  describe('getStorageKey', () => {
+    it('should return base key when identifier is undefined', async () => {
+      const storageKey = createStorageKey('wallet_encryption_key')
+      const key = await getStorageKey(storageKey, undefined)
+      expect(key).toBe('wallet_encryption_key')
+    })
+
+    it('should return base key when identifier is null', async () => {
+      const storageKey = createStorageKey('wallet_encryption_key')
+      const key = await getStorageKey(storageKey, null as any)
+      expect(key).toBe('wallet_encryption_key')
+    })
+
+    it('should generate hashed key for identifier', async () => {
+      const storageKey = createStorageKey('wallet_encryption_key')
+      const key = await getStorageKey(storageKey, 'user@example.com')
+      expect(key).toContain('wallet_encryption_key')
+      expect(key).not.toBe('wallet_encryption_key')
+      expect(key.length).toBeGreaterThan('wallet_encryption_key'.length)
+    })
+
+    it('should normalize identifier (lowercase and trim)', async () => {
+      const storageKey = createStorageKey('wallet_encryption_key')
+      const key1 = await getStorageKey(storageKey, 'User@Example.com')
+      const key2 = await getStorageKey(storageKey, '  user@example.com  ')
+      expect(key1).toBe(key2)
+    })
+
+    it('should throw ValidationError for invalid storage key', async () => {
+      await expect(
+        getStorageKey('invalid_key' as any, 'user@example.com')
+      ).rejects.toThrow(ValidationError)
+    })
+  })
+
+  describe('withTimeout', () => {
+    it('should resolve if promise completes before timeout', async () => {
+      const promise = Promise.resolve('success')
+      const result = await withTimeout(promise, 1000, 'test')
+      expect(result).toBe('success')
+    })
+
+    it('should throw TimeoutError if promise exceeds timeout', async () => {
+      const promise = new Promise((resolve) => {
+        setTimeout(() => resolve('too late'), 2000)
+      })
+      
+      await expect(withTimeout(promise, MIN_TIMEOUT_MS, 'test')).rejects.toThrow(TimeoutError)
+    }, 5000)
+
+    it('should throw ValidationError for negative timeout', async () => {
+      const promise = Promise.resolve('success')
+      await expect(withTimeout(promise, -1000, 'test')).rejects.toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for zero timeout', async () => {
+      const promise = Promise.resolve('success')
+      await expect(withTimeout(promise, 0, 'test')).rejects.toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for timeout below minimum', async () => {
+      const promise = Promise.resolve('success')
+      await expect(withTimeout(promise, MIN_TIMEOUT_MS - 1, 'test')).rejects.toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for timeout above maximum', async () => {
+      const promise = Promise.resolve('success')
+      await expect(withTimeout(promise, MAX_TIMEOUT_MS + 1, 'test')).rejects.toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for NaN timeout', async () => {
+      const promise = Promise.resolve('success')
+      await expect(withTimeout(promise, NaN, 'test')).rejects.toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for Infinity timeout', async () => {
+      const promise = Promise.resolve('success')
+      await expect(withTimeout(promise, Infinity, 'test')).rejects.toThrow(ValidationError)
+    })
+
+    it('should accept valid timeout values', async () => {
+      const promise = Promise.resolve('success')
+      const result = await withTimeout(promise, MIN_TIMEOUT_MS, 'test')
+      expect(result).toBe('success')
+    })
+
+    it('should accept maximum timeout value', async () => {
+      const promise = Promise.resolve('success')
+      const result = await withTimeout(promise, MAX_TIMEOUT_MS, 'test')
+      expect(result).toBe('success')
+    })
+  })
+
+
+  describe('isKeychainCredentials', () => {
+    it('should return true for valid credentials', () => {
+      const credentials = {
+        username: 'test',
+        password: 'password123',
+        service: 'test-service',
+        storage: 'AES_GCM',
+      }
+      expect(isKeychainCredentials(credentials)).toBe(true)
+    })
+
+    it('should return true for credentials without storage', () => {
+      const credentials = {
+        username: 'test',
+        password: 'password123',
+        service: 'test-service',
+      }
+      expect(isKeychainCredentials(credentials)).toBe(true)
+    })
+
+    it('should return false for false', () => {
+      expect(isKeychainCredentials(false)).toBe(false)
+    })
+
+    it('should return false for null', () => {
+      expect(isKeychainCredentials(null)).toBe(false)
+    })
+
+    it('should return false for undefined', () => {
+      expect(isKeychainCredentials(undefined)).toBe(false)
+    })
+
+    it('should return false for non-object', () => {
+      expect(isKeychainCredentials('string')).toBe(false)
+      expect(isKeychainCredentials(123)).toBe(false)
+      expect(isKeychainCredentials([])).toBe(false)
+    })
+
+    it('should return false for object without password', () => {
+      expect(isKeychainCredentials({ username: 'test', service: 'test' })).toBe(false)
+    })
+
+    it('should return false for object with non-string password', () => {
+      expect(isKeychainCredentials({ username: 'test', password: 123, service: 'test' })).toBe(false)
+      expect(isKeychainCredentials({ username: 'test', password: null, service: 'test' })).toBe(false)
+    })
+
+    it('should return false for object with empty password', () => {
+      expect(isKeychainCredentials({ username: 'test', password: '', service: 'test' })).toBe(false)
+    })
+
+    it('should return true for object with non-empty password string', () => {
+      expect(isKeychainCredentials({ username: 'test', password: 'a', service: 'test' })).toBe(true)
+      expect(isKeychainCredentials({ username: 'test', password: 'valid', service: 'test' })).toBe(true)
+    })
+  })
+
+})
+

package/src/__tests__/validation.test.ts

@@ -0,0 +1,222 @@
+import { validateIdentifier, validateValue, validateTimeout, validateAuthenticationOptions, MAX_IDENTIFIER_LENGTH, MAX_VALUE_LENGTH } from '../validation'
+import { ValidationError } from '../errors'
+import { MIN_TIMEOUT_MS, MAX_TIMEOUT_MS } from '../constants'
+
+describe('validation', () => {
+  describe('validateIdentifier', () => {
+    it('should allow undefined identifier', () => {
+      expect(() => validateIdentifier(undefined)).not.toThrow()
+    })
+
+    it('should allow null identifier', () => {
+      expect(() => validateIdentifier(null as any)).not.toThrow()
+    })
+
+    it('should allow valid email identifier', () => {
+      expect(() => validateIdentifier('user@example.com')).not.toThrow()
+    })
+
+    it('should allow email identifier with plus sign', () => {
+      expect(() => validateIdentifier('dario.moceri+3@tether.to')).not.toThrow()
+      expect(() => validateIdentifier('user+tag@example.com')).not.toThrow()
+    })
+
+    it('should allow valid alphanumeric identifier', () => {
+      expect(() => validateIdentifier('user123')).not.toThrow()
+      expect(() => validateIdentifier('user_123')).not.toThrow()
+      expect(() => validateIdentifier('user-123')).not.toThrow()
+      expect(() => validateIdentifier('user.123')).not.toThrow()
+    })
+
+    it('should throw ValidationError for non-string identifier', () => {
+      expect(() => validateIdentifier(123 as any)).toThrow(ValidationError)
+      expect(() => validateIdentifier({} as any)).toThrow(ValidationError)
+      expect(() => validateIdentifier([] as any)).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for empty string', () => {
+      expect(() => validateIdentifier('')).toThrow(ValidationError)
+      expect(() => validateIdentifier('   ')).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for identifier exceeding max length', () => {
+      const longIdentifier = 'a'.repeat(MAX_IDENTIFIER_LENGTH + 1)
+      expect(() => validateIdentifier(longIdentifier)).toThrow(ValidationError)
+    })
+
+    it('should allow identifier at max length', () => {
+      const maxIdentifier = 'a'.repeat(MAX_IDENTIFIER_LENGTH)
+      expect(() => validateIdentifier(maxIdentifier)).not.toThrow()
+    })
+
+    it('should throw ValidationError for invalid characters', () => {
+      expect(() => validateIdentifier('user@#$%example')).toThrow(ValidationError)
+      expect(() => validateIdentifier('user example')).toThrow(ValidationError)
+      expect(() => validateIdentifier('user\nexample')).toThrow(ValidationError)
+    })
+  })
+
+  describe('validateValue', () => {
+    it('should allow valid non-empty string', () => {
+      expect(() => validateValue('valid value')).not.toThrow()
+      expect(() => validateValue('a')).not.toThrow()
+    })
+
+    it('should throw ValidationError for null', () => {
+      expect(() => validateValue(null as any, 'test')).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for undefined', () => {
+      expect(() => validateValue(undefined as any, 'test')).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for non-string', () => {
+      expect(() => validateValue(123 as any, 'test')).toThrow(ValidationError)
+      expect(() => validateValue({} as any, 'test')).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for empty string', () => {
+      expect(() => validateValue('', 'test')).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for value exceeding max length', () => {
+      const longValue = 'a'.repeat(MAX_VALUE_LENGTH + 1)
+      expect(() => validateValue(longValue, 'test')).toThrow(ValidationError)
+    })
+
+    it('should allow value at max length', () => {
+      const maxValue = 'a'.repeat(MAX_VALUE_LENGTH)
+      expect(() => validateValue(maxValue, 'test')).not.toThrow()
+    })
+
+    it('should use custom field name in error message', () => {
+      try {
+        validateValue('', 'customField')
+      } catch (error) {
+        expect(error).toBeInstanceOf(ValidationError)
+        expect((error as ValidationError).message).toContain('customField')
+      }
+    })
+  })
+
+  describe('validateTimeout', () => {
+    it('should allow undefined timeout', () => {
+      expect(() => validateTimeout(undefined)).not.toThrow()
+      expect(validateTimeout(undefined)).toBeUndefined()
+    })
+
+    it('should allow valid timeout within range', () => {
+      expect(() => validateTimeout(MIN_TIMEOUT_MS)).not.toThrow()
+      expect(() => validateTimeout(MAX_TIMEOUT_MS)).not.toThrow()
+      expect(() => validateTimeout(30000)).not.toThrow()
+      expect(validateTimeout(30000)).toBe(30000)
+    })
+
+    it('should throw ValidationError for non-number', () => {
+      expect(() => validateTimeout('1000' as any)).toThrow(ValidationError)
+      expect(() => validateTimeout(null as any)).toThrow(ValidationError)
+      expect(() => validateTimeout({} as any)).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for NaN', () => {
+      expect(() => validateTimeout(NaN)).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for Infinity', () => {
+      expect(() => validateTimeout(Infinity)).toThrow(ValidationError)
+      expect(() => validateTimeout(-Infinity)).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for timeout too short', () => {
+      expect(() => validateTimeout(MIN_TIMEOUT_MS - 1)).toThrow(ValidationError)
+      expect(() => validateTimeout(0)).toThrow(ValidationError)
+      expect(() => validateTimeout(-1000)).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for timeout too long', () => {
+      expect(() => validateTimeout(MAX_TIMEOUT_MS + 1)).toThrow(ValidationError)
+    })
+
+    it('should return the timeout value when valid', () => {
+      expect(validateTimeout(5000)).toBe(5000)
+      expect(validateTimeout(MIN_TIMEOUT_MS)).toBe(MIN_TIMEOUT_MS)
+      expect(validateTimeout(MAX_TIMEOUT_MS)).toBe(MAX_TIMEOUT_MS)
+    })
+  })
+
+  describe('validateAuthenticationOptions', () => {
+    it('should allow undefined options', () => {
+      expect(() => validateAuthenticationOptions(undefined)).not.toThrow()
+    })
+
+    it('should allow empty options object', () => {
+      expect(() => validateAuthenticationOptions({})).not.toThrow()
+    })
+
+    it('should allow valid promptMessage', () => {
+      expect(() => validateAuthenticationOptions({ promptMessage: 'Authenticate' })).not.toThrow()
+      expect(() => validateAuthenticationOptions({ promptMessage: 'Please authenticate' })).not.toThrow()
+    })
+
+    it('should throw ValidationError for non-string promptMessage', () => {
+      expect(() => validateAuthenticationOptions({ promptMessage: 123 as any })).toThrow(ValidationError)
+      expect(() => validateAuthenticationOptions({ promptMessage: null as any })).toThrow(ValidationError)
+      expect(() => validateAuthenticationOptions({ promptMessage: {} as any })).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for empty promptMessage', () => {
+      expect(() => validateAuthenticationOptions({ promptMessage: '' })).toThrow(ValidationError)
+      expect(() => validateAuthenticationOptions({ promptMessage: '   ' })).toThrow(ValidationError)
+    })
+
+    it('should allow valid cancelLabel', () => {
+      expect(() => validateAuthenticationOptions({ cancelLabel: 'Cancel' })).not.toThrow()
+      expect(() => validateAuthenticationOptions({ cancelLabel: 'Abort' })).not.toThrow()
+    })
+
+    it('should throw ValidationError for non-string cancelLabel', () => {
+      expect(() => validateAuthenticationOptions({ cancelLabel: 123 as any })).toThrow(ValidationError)
+      expect(() => validateAuthenticationOptions({ cancelLabel: null as any })).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for empty cancelLabel', () => {
+      expect(() => validateAuthenticationOptions({ cancelLabel: '' })).toThrow(ValidationError)
+      expect(() => validateAuthenticationOptions({ cancelLabel: '   ' })).toThrow(ValidationError)
+    })
+
+    it('should allow valid disableDeviceFallback', () => {
+      expect(() => validateAuthenticationOptions({ disableDeviceFallback: true })).not.toThrow()
+      expect(() => validateAuthenticationOptions({ disableDeviceFallback: false })).not.toThrow()
+    })
+
+    it('should throw ValidationError for non-boolean disableDeviceFallback', () => {
+      expect(() => validateAuthenticationOptions({ disableDeviceFallback: 'true' as any })).toThrow(ValidationError)
+      expect(() => validateAuthenticationOptions({ disableDeviceFallback: 1 as any })).toThrow(ValidationError)
+      expect(() => validateAuthenticationOptions({ disableDeviceFallback: null as any })).toThrow(ValidationError)
+    })
+
+    it('should allow all options together', () => {
+      expect(() => validateAuthenticationOptions({
+        promptMessage: 'Authenticate',
+        cancelLabel: 'Cancel',
+        disableDeviceFallback: true,
+      })).not.toThrow()
+    })
+
+    it('should validate each option independently', () => {
+      // Valid promptMessage, invalid cancelLabel
+      expect(() => validateAuthenticationOptions({
+        promptMessage: 'Authenticate',
+        cancelLabel: '',
+      })).toThrow(ValidationError)
+
+      // Valid cancelLabel, invalid promptMessage
+      expect(() => validateAuthenticationOptions({
+        promptMessage: '',
+        cancelLabel: 'Cancel',
+      })).toThrow(ValidationError)
+    })
+  })
+})
+
+

package/src/constants.ts

@@ -0,0 +1,12 @@
+/**
+ * Timeout constants for keychain operations
+ */
+export const DEFAULT_TIMEOUT_MS = 30000
+export const MIN_TIMEOUT_MS = 1000
+export const MAX_TIMEOUT_MS = 5 * 60 * 1000
+
+/**
+ * Cache TTL for device authentication availability (5 minutes)
+ */
+export const DEVICE_AUTH_CACHE_TTL_MS = 5 * 60 * 1000
+

package/src/errors.ts

@@ -0,0 +1,97 @@
+/**
+ * Base error class for all secure storage errors
+ */
+export class SecureStorageError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly cause?: Error
+  ) {
+    super(message)
+    this.name = 'SecureStorageError'
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    // Note: Error.captureStackTrace is V8-specific (Node.js, Chrome). In React Native,
+    // this will typically work on Android (V8) but may not work on iOS (JavaScriptCore).
+    // If unavailable, the standard Error stack trace will be used instead.
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+}
+
+/**
+ * Error thrown when keychain operations fail
+ * 
+ * Note: This is a base error class for completeness. In practice, use
+ * KeychainWriteError or KeychainReadError for more specific error handling.
+ */
+export class KeychainError extends SecureStorageError {
+  constructor(message: string, cause?: Error) {
+    super(message, 'KEYCHAIN_ERROR', cause)
+    this.name = 'KeychainError'
+  }
+}
+
+/**
+ * Error thrown when keychain write operations fail
+ */
+export class KeychainWriteError extends SecureStorageError {
+  constructor(message: string, cause?: Error) {
+    super(message, 'KEYCHAIN_WRITE_ERROR', cause)
+    this.name = 'KeychainWriteError'
+  }
+}
+
+/**
+ * Error thrown when keychain read operations fail
+ */
+export class KeychainReadError extends SecureStorageError {
+  constructor(message: string, cause?: Error) {
+    super(message, 'KEYCHAIN_READ_ERROR', cause)
+    this.name = 'KeychainReadError'
+  }
+}
+
+/**
+ * Error thrown when authentication fails or is required but unavailable
+ */
+export class AuthenticationError extends SecureStorageError {
+  constructor(message: string, cause?: Error) {
+    super(message, 'AUTHENTICATION_ERROR', cause)
+    this.name = 'AuthenticationError'
+  }
+}
+
+/**
+ * Error thrown when input validation fails
+ */
+export class ValidationError extends SecureStorageError {
+  constructor(message: string) {
+    super(message, 'VALIDATION_ERROR')
+    this.name = 'ValidationError'
+  }
+}
+
+/**
+ * Error thrown when an operation times out
+ */
+export class TimeoutError extends SecureStorageError {
+  constructor(message: string) {
+    super(message, 'TIMEOUT_ERROR')
+    this.name = 'TimeoutError'
+  }
+}
+
+/**
+ * Error thrown when device security (PIN/pattern/password/biometrics) is not enabled
+ * 
+ * This error can be used by apps that want to enforce device security as a prerequisite.
+ * Whether to require device security is up to the app - the library will still function
+ * on devices without authentication configured (data remains encrypted at rest).
+ */
+export class DeviceSecurityNotEnabledError extends SecureStorageError {
+  constructor(message: string = 'Device security is not enabled. Please set up a PIN, pattern, or password in your device settings to use secure wallet storage.', cause?: Error) {
+    super(message, 'DEVICE_SECURITY_NOT_ENABLED', cause)
+    this.name = 'DeviceSecurityNotEnabledError'
+  }
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @tetherto/wdk-react-native-secure-storage
+ *
+ * Secure storage abstractions for React Native
+ * Provides secure storage for sensitive data (encrypted seeds, keys)
+ * 
+ * **Note on Internal Types:** Some internal types like `StorageKey` are intentionally
+ * not exported. These are implementation details that consumers should not use directly.
+ * Use the public API methods (setEncryptionKey, getEncryptionKey, etc.) instead.
+ */
+
+// Main types and factory
+export type {
+  SecureStorage,
+  SecureStorageOptions,
+  AuthenticationOptions,
+  SecureStorageItemOptions,
+} from './secureStorage'
+export { createSecureStorage } from './secureStorage'
+
+// Error classes
+export {
+  SecureStorageError,
+  KeychainError,
+  KeychainWriteError,
+  KeychainReadError,
+  AuthenticationError,
+  ValidationError,
+  TimeoutError,
+  DeviceSecurityNotEnabledError,
+} from './errors'
+
+// Logger types
+export type { Logger, LogEntry } from './logger'
+export { LogLevel, defaultLogger } from './logger'
+
+// Validation constants
+export { MAX_IDENTIFIER_LENGTH, MAX_VALUE_LENGTH } from './validation'
+
+// Timeout constants
+export { MIN_TIMEOUT_MS, MAX_TIMEOUT_MS } from './constants'

package/src/keychainHelpers.ts

@@ -0,0 +1,34 @@
+import * as Keychain from 'react-native-keychain'
+
+/**
+ * Keychain options for setGenericPassword
+ */
+export type KeychainOptions = Parameters<typeof Keychain.setGenericPassword>[2]
+
+/**
+ * Create keychain options with conditional access control
+ * 
+ * @param deviceAuthAvailable - Whether device authentication (biometrics/PIN) is available
+ * @param requireAuth - Whether authentication should be required for this operation
+ * @param syncable - Whether the value should sync across devices (default: true)
+ * @returns Keychain options object with appropriate access control settings
+ */
+export function createKeychainOptions(
+  deviceAuthAvailable: boolean,
+  requireAuth: boolean = true,
+  syncable: boolean = true
+): KeychainOptions {
+  const options: KeychainOptions = {
+    accessible: syncable 
+      ? Keychain.ACCESSIBLE.WHEN_UNLOCKED 
+      : Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+  }
+  
+  if (requireAuth && deviceAuthAvailable) {
+    options.accessControl = Keychain.ACCESS_CONTROL.BIOMETRY_ANY_OR_DEVICE_PASSCODE
+  }
+  
+  return options
+}
+
+