npm package: @stochain/secure-storage
Description: Secure storage utilities for React Native with encryption
Author: Stochain
Latest version: 1.0.0

# @stochain/secure-storage

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

## Installation

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

### iOS Setup

```bash
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

```typescript
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

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

### Get All Keys

```typescript
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

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

### Biometric Authentication

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

## API Reference

### Constructor

```typescript
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

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

## Use Cases

### Wallet Private Keys

```typescript
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

```typescript
await storage.setItem('credentials', {
  username: 'user@example.com',
  refreshToken: 'xyz789'
});

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

### App Settings

```typescript
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