@stochain/secure-storage

Encrypted storage wrapper for React Native applications with key-value persistence.

Installation

npm install @stochain/secure-storage
npm install react-native-sensitive-info

iOS Setup

cd ios && pod install

Android Setup

No additional setup required.

Features

• AES-256 encryption by default
• Keychain (iOS) / Keystore (Android) integration
• Simple key-value storage interface
• TypeScript support
• Automatic JSON serialization
• Biometric authentication support

Usage

Basic Operations

import { SecureStorage } from '@stochain/secure-storage';

const storage = new SecureStorage();

// Store data
await storage.setItem('user', { id: 1, name: 'John' });
await storage.setItem('token', 'abc123');

// Retrieve data
const user = await storage.getItem<{ id: number; name: string }>('user');
const token = await storage.getItem<string>('token');

// Delete data
await storage.removeItem('token');

// Clear all data
await storage.clear();

Check if Key Exists

const hasToken = await storage.hasItem('token'); // true or false

Get All Keys

const keys = await storage.getAllKeys(); // ['user', 'token', ...]

Security Features

Encryption

All data is encrypted using:

• iOS: AES-256 encryption with Keychain storage
• Android: AES-256 encryption with Keystore system

Access Control

const storage = new SecureStorage({
  sharedPreferencesName: 'myAppPrefs',
  keychainService: 'myAppKeychain'
});

Biometric Authentication

// Require biometric authentication for access
const sensitiveData = await storage.getItem('privateKey', {
  touchID: true,
  showModal: true
});

API Reference

Constructor

new SecureStorage(options?: SecureStorageOptions)

Methods

• setItem<T>(key: string, value: T): Promise<void> - Store encrypted data
• getItem<T>(key: string): Promise<T | null> - Retrieve decrypted data
• removeItem(key: string): Promise<void> - Delete specific key
• hasItem(key: string): Promise<boolean> - Check if key exists
• getAllKeys(): Promise<string[]> - Get all stored keys
• clear(): Promise<void> - Delete all stored data

TypeScript Types

interface SecureStorageOptions {
  sharedPreferencesName?: string;
  keychainService?: string;
}

Use Cases

Wallet Private Keys

const storage = new SecureStorage();

// Store private key securely
await storage.setItem('wallet_private_key', privateKey);

// Retrieve with biometric auth
const key = await storage.getItem<string>('wallet_private_key');

User Credentials

await storage.setItem('credentials', {
  username: '[email protected]',
  refreshToken: 'xyz789'
});

const creds = await storage.getItem<{
  username: string;
  refreshToken: string;
}>('credentials');

App Settings

await storage.setItem('settings', {
  darkMode: true,
  notifications: false,
  language: 'en'
});

Security Best Practices

1. Never log sensitive data: Avoid console.log with encrypted values
2. Use TypeScript: Type safety prevents accidental data exposure
3. Clear on logout: Remove sensitive data when user logs out
4. Biometric protection: Enable for highly sensitive operations
5. Key naming: Use descriptive, non-obvious key names

Platform Support

• iOS 10.0+
• Android API 21+

License

MIT

Repository

https://github.com/stochain/packages