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

package/LICENSE

@@ -0,0 +1,180 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (which shall not include Communications that are clearly marked or
+   otherwise designated in writing by the copyright owner as "Not a Work").
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is clearly marked or otherwise designated
+   in writing by the copyright owner as "Not a Contribution".
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+
+

package/README.md

@@ -0,0 +1,472 @@
+# @tetherto/wdk-react-native-secure-storage
+
+Secure storage abstractions for React Native - provides secure storage for sensitive data (encrypted seeds, keys) using react-native-keychain.
+
+## Features
+
+- 🔒 Secure storage using native keychain/keystore
+- 📱 iOS Keychain integration with selective iCloud sync
+- 🤖 Android Keystore integration with selective Google Cloud backup
+- 🔐 Biometric authentication support
+- 💾 Encrypted data storage at rest
+- ✅ Comprehensive input validation
+- 📊 Structured logging support
+- ⏱️ Configurable timeouts
+- 🎯 TypeScript support with full type safety
+
+## Installation
+
+### From npm (Recommended for Production)
+
+```bash
+npm install @tetherto/wdk-react-native-secure-storage
+```
+
+### From GitHub (Development/Unpublished Versions)
+
+If the package is not yet published to npm, you can install directly from GitHub:
+
+```bash
+npm install https://github.com/tetherto/wdk-react-native-secure-storage.git
+```
+
+Or add to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@tetherto/wdk-react-native-secure-storage": "github:tetherto/wdk-react-native-secure-storage"
+  }
+}
+```
+
+Then run `npm install`.
+
+## Peer Dependencies
+
+```bash
+npm install react-native@">=0.70.0"
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createSecureStorage } from '@tetherto/wdk-react-native-secure-storage'
+
+// Create storage instance
+const storage = createSecureStorage()
+
+// Store encryption key
+await storage.setEncryptionKey('my-encryption-key', 'user@example.com')
+
+// Retrieve encryption key
+const key = await storage.getEncryptionKey('user@example.com')
+if (key) {
+  console.log('Key retrieved:', key)
+}
+
+// Store encrypted seed
+await storage.setEncryptedSeed('encrypted-seed-data', 'user@example.com')
+
+// Store encrypted entropy
+await storage.setEncryptedEntropy('encrypted-entropy-data', 'user@example.com')
+
+// Get all encrypted data
+const allData = await storage.getAllEncrypted('user@example.com')
+console.log('All data:', allData)
+
+// Check if wallet exists
+const exists = await storage.hasWallet('user@example.com')
+
+// Delete wallet
+await storage.deleteWallet('user@example.com')
+```
+
+### Advanced Usage with Options
+
+```typescript
+import { createSecureStorage, defaultLogger, LogLevel } from '@tetherto/wdk-react-native-secure-storage'
+
+// Configure logger
+defaultLogger.setLevel(LogLevel.INFO)
+
+// Create storage with custom options
+const storage = createSecureStorage({
+  logger: customLogger, // Optional custom logger
+  authentication: {
+    promptMessage: 'Authenticate to access your wallet',
+    cancelLabel: 'Cancel',
+    disableDeviceFallback: false,
+  },
+  timeoutMs: 30000, // 30 seconds default
+})
+
+// Use storage
+await storage.setEncryptionKey('key', 'user@example.com')
+```
+
+### Error Handling
+
+```typescript
+import {
+  createSecureStorage,
+  ValidationError,
+  KeychainWriteError,
+  KeychainReadError,
+  AuthenticationError,
+  TimeoutError,
+} from '@tetherto/wdk-react-native-secure-storage'
+
+const storage = createSecureStorage()
+
+try {
+  await storage.setEncryptionKey('my-key', 'user@example.com')
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('Invalid input:', error.message)
+  } else if (error instanceof KeychainWriteError) {
+    console.error('Failed to write to keychain:', error.message)
+  } else if (error instanceof TimeoutError) {
+    console.error('Operation timed out:', error.message)
+  } else {
+    console.error('Unexpected error:', error)
+  }
+}
+
+try {
+  const key = await storage.getEncryptionKey('user@example.com')
+  if (!key) {
+    console.log('Key not found')
+  }
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Authentication failed:', error.message)
+  } else if (error instanceof KeychainReadError) {
+    console.error('Failed to read from keychain:', error.message)
+  }
+}
+```
+
+### Multiple Wallets
+
+The identifier parameter allows you to support multiple wallets:
+
+```typescript
+// Store data for different users
+await storage.setEncryptionKey('key1', 'user1@example.com')
+await storage.setEncryptionKey('key2', 'user2@example.com')
+
+// Retrieve specific user's data
+const key1 = await storage.getEncryptionKey('user1@example.com')
+const key2 = await storage.getEncryptionKey('user2@example.com')
+```
+
+## API Reference
+
+### `createSecureStorage(options?)`
+
+Creates a new instance of secure storage. Each call returns a new instance with the specified options.
+For most apps, you should create one instance and reuse it throughout your application.
+
+**Options:**
+- `logger?: Logger` - Custom logger instance
+- `authentication?: AuthenticationOptions` - Authentication prompt configuration
+- `timeoutMs?: number` - Timeout for keychain operations (default: 30000ms, min: 1000ms, max: 300000ms)
+
+**Returns:** `SecureStorage` instance
+
+### `SecureStorage` Interface
+
+#### `setEncryptionKey(key: string, identifier?: string): Promise<void>`
+
+Stores an encryption key securely.
+
+**Parameters:**
+- `key: string` - The encryption key (max 10KB, non-empty)
+- `identifier?: string` - Optional identifier for multiple wallets (max 256 chars)
+
+**Throws:**
+- `ValidationError` - If input is invalid
+- `KeychainWriteError` - If keychain operation fails
+- `TimeoutError` - If operation times out
+
+#### `getEncryptionKey(identifier?: string): Promise<string | null>`
+
+Retrieves an encryption key.
+
+**Parameters:**
+- `identifier?: string` - Optional identifier
+
+**Returns:** The encryption key or `null` if not found
+
+**Throws:**
+- `ValidationError` - If identifier is invalid
+- `AuthenticationError` - If authentication fails
+- `KeychainReadError` - If keychain operation fails
+- `TimeoutError` - If operation times out
+
+#### `setEncryptedSeed(encryptedSeed: string, identifier?: string): Promise<void>`
+
+Stores encrypted seed data.
+
+#### `getEncryptedSeed(identifier?: string): Promise<string | null>`
+
+Retrieves encrypted seed data.
+
+#### `setEncryptedEntropy(encryptedEntropy: string, identifier?: string): Promise<void>`
+
+Stores encrypted entropy data.
+
+#### `getEncryptedEntropy(identifier?: string): Promise<string | null>`
+
+Retrieves encrypted entropy data.
+
+#### `getAllEncrypted(identifier?: string): Promise<{encryptedSeed: string | null, encryptedEntropy: string | null, encryptionKey: string | null}>`
+
+Retrieves all encrypted wallet data at once.
+
+#### `hasWallet(identifier?: string): Promise<boolean>`
+
+Checks if wallet credentials exist.
+
+#### `deleteWallet(identifier?: string): Promise<void>`
+
+Deletes all wallet credentials.
+
+**Throws:**
+- `ValidationError` - If identifier is invalid
+- `SecureStorageError` - If deletion fails (with details of which items failed)
+- `TimeoutError` - If operation times out
+
+#### `isBiometricAvailable(): Promise<boolean>`
+
+Checks if biometric authentication is available.
+
+#### `authenticate(): Promise<boolean>`
+
+Authenticates with biometrics. Returns `true` if successful, `false` otherwise.
+
+**Throws:**
+- `AuthenticationError` - If authentication fails
+
+
+### Logger Interface
+
+The module provides a `Logger` interface for structured logging. The default logger can be configured:
+
+```typescript
+import { defaultLogger, LogLevel } from '@tetherto/wdk-react-native-secure-storage'
+
+// Set the minimum log level (logs below this level will be ignored)
+defaultLogger.setLevel(LogLevel.INFO)
+
+// Available log levels: DEBUG, INFO, WARN, ERROR
+```
+
+You can also provide a custom logger that implements the `Logger` interface:
+
+```typescript
+const customLogger: Logger = {
+  debug: (message, context) => { /* ... */ },
+  info: (message, context) => { /* ... */ },
+  warn: (message, context) => { /* ... */ },
+  error: (message, error, context) => { /* ... */ },
+  setLevel: (level) => { /* optional */ },
+}
+
+const storage = createSecureStorage({ logger: customLogger })
+```
+
+## Module Lifecycle & Resource Management
+
+The module has no shared state or cleanup requirements. Each storage instance is independent and can be used without any module-level lifecycle management.
+
+## Security Features
+
+### Input Validation
+- All inputs are validated before processing
+- Maximum length limits enforced (10KB for values, 256 chars for identifiers)
+- Invalid characters rejected
+- Type checking at runtime
+- All validation happens before any side effects
+
+### Error Handling
+- Comprehensive error types for different failure scenarios
+- Detailed error messages
+- Proper error propagation
+
+### Logging
+- Structured logging for security events
+- Configurable log levels
+- No sensitive data in logs
+
+## Error Types
+
+- `SecureStorageError` - Base error class
+- `KeychainError` - Keychain operation errors
+- `KeychainWriteError` - Keychain write failures
+- `KeychainReadError` - Keychain read failures
+- `AuthenticationError` - Authentication failures
+- `ValidationError` - Input validation failures
+- `TimeoutError` - Operation timeout errors
+
+## Development
+
+### Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Code Quality
+
+```bash
+# Type checking
+npm run typecheck
+
+# Linting
+npm run lint
+npm run lint:fix
+
+# Formatting
+npm run format
+npm run format:check
+```
+
+**Note:** ESLint and Prettier are configured but need to be installed as dev dependencies:
+```bash
+npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin prettier
+```
+
+## Production Readiness
+
+This module is production-ready and includes:
+
+✅ **Built and tested** - All code is compiled to JavaScript with TypeScript definitions  
+✅ **Proper exports** - Only necessary files are included in the npm package  
+✅ **Security hardened** - Input validation and secure storage with device-level protections  
+✅ **Error handling** - Comprehensive error types for all failure scenarios  
+✅ **Logging** - Structured logging with configurable levels (defaults to ERROR in production)  
+✅ **Type safety** - Full TypeScript support with exported types  
+✅ **Documentation** - Complete API documentation and usage examples  
+
+### Production Best Practices
+
+1. **Configure Logging**: Set appropriate log levels for your environment:
+   ```typescript
+   import { defaultLogger, LogLevel } from '@tetherto/wdk-react-native-secure-storage'
+   
+   // In production, only log errors and warnings
+   defaultLogger.setLevel(LogLevel.WARN)
+   
+   // In development, you might want more verbose logging
+   if (__DEV__) {
+     defaultLogger.setLevel(LogLevel.DEBUG)
+   }
+   ```
+
+2. **Error Handling**: Always handle errors appropriately:
+   ```typescript
+   try {
+     await storage.setEncryptionKey(key, identifier)
+   } catch (error) {
+     // Log error to your error tracking service (e.g., Sentry)
+     // Never log sensitive data like keys or seeds
+     if (error instanceof ValidationError) {
+       // Handle validation errors
+     } else if (error instanceof KeychainWriteError) {
+       // Handle keychain errors
+     }
+   }
+   ```
+
+3. **Single Instance**: Create one storage instance and reuse it:
+   ```typescript
+   // Good: Create once and reuse
+   const storage = createSecureStorage({ logger: customLogger })
+   
+   // Avoid: Creating multiple instances unnecessarily
+   ```
+
+## Security Considerations
+
+- Data is encrypted at rest by iOS Keychain / Android Keystore
+- Cloud sync behavior:
+  - **Encryption key**: Synced via iCloud Keychain (iOS) and Google Cloud backup (Android)
+  - **Encrypted seed and entropy**: Device-only storage (not synced across devices)
+- Biometric authentication required when available
+- Device-level keychain/keystore provides rate limiting and lockout mechanisms
+- **No sensitive data is logged** - The logger only logs error messages and metadata
+
+## Security Limitations
+
+⚠️ **Important Security Notes:**
+
+1. **Timeout Resource Usage**: The timeout implementation uses `Promise.race()` which does NOT cancel the underlying keychain operation. The operation continues executing even after timeout, though its result is ignored. This means:
+   - Under extreme load, timed-out keychain operations may continue executing in the background
+   - Memory and resources are not immediately freed on timeout
+   - This is generally acceptable because:
+     - Keychain operations are typically fast (< 1 second)
+     - They are bounded in duration by the OS
+     - Timeouts are a safety mechanism, not a normal occurrence
+     - React Native's single-threaded nature limits concurrent operations
+   - **Monitoring**: In production, monitor timeout frequency. If timeouts occur frequently, investigate keychain performance or increase timeout values.
+
+2. **Device Authentication**: On devices without authentication (no PIN/password/biometrics), data is still encrypted at rest but accessible when the device is unlocked. This is a limitation of the underlying platform security model.
+
+3. **Device-Level Rate Limiting**: The module relies on device-level keychain/keystore rate limiting and lockout mechanisms. These are more robust than app-level rate limiting and persist across app restarts.
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests (`npm test`)
+5. Run type checking (`npm run typecheck`)
+6. Run linting (`npm run lint`)
+7. Format code (`npm run format`)
+8. Build the project (`npm run build`)
+9. Commit your changes (`git commit -m 'Add amazing feature'`)
+10. Push to the branch (`git push origin feature/amazing-feature`)
+11. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/tetherto/wdk-react-native-secure-storage.git
+cd wdk-react-native-secure-storage
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run type checking
+npm run typecheck
+
+# Run linting
+npm run lint
+
+# Format code
+npm run format
+
+# Build
+npm run build
+```
+
+## License
+
+Apache-2.0