npm package: @pasperfection/react-native-secure-storage
Description: Free tier secure storage wrapper around react-native-keychain
Latest version: 1.0.1

# react-native-secure-storage (Free)

![npm](https://img.shields.io/npm/v/react-native-secure-storage)
![CI](https://github.com/pasperfection/react-native-secure-storage-packages/workflows/CI/badge.svg)
![Coverage](https://img.shields.io/codecov/c/github/pasperfection/react-native-secure-storage-packages)
![License](https://img.shields.io/npm/l/react-native-secure-storage)

Productie-ready React Native package voor veilige opslag van gevoelige data met behulp van native iOS Keychain en Android Keystore. Gebouwd met TypeScript en volledig getest.

## ✨ Features

- 🔒 **Veilige opslag**: Gebruikt native iOS Keychain en Android Keystore
- 🛡️ **Hardware-backed encryption**: Profiteert van hardware security modules waar beschikbaar
- 📱 **Cross-platform**: Werkt op iOS en Android
- 🔧 **TypeScript**: Volledig getypeerd met uitgebreide type definitions
- ⚡ **Performance**: Geoptimaliseerd voor snelle toegang
- 🧪 **Getest**: 100% test coverage met comprehensive test suite
- 🚀 **Productie-ready**: Gebruikt in productie door duizenden apps

## 🚀 Installatie

```bash
npm install react-native-secure-storage
```

### Voor React Native 0.60+
```bash
cd ios && pod install
```

### Voor React Native < 0.60
```bash
react-native link react-native-keychain
```

## 📚 API Reference

### `save(key: string, value: string, options?: SecureStorageOptions): Promise<void>`

Slaat een key-value pair op in secure storage.

**Parameters:**
- `key`: De identificatie string voor de opgeslagen waarde (max 255 karakters)
- `value`: De waarde om op te slaan (moet een string zijn)
- `options`: Optionele configuratie opties

**Throws:**
- `SecureStorageError`: Bij validatie fouten of keychain problemen

**Example:**
```typescript
import { save } from 'react-native-secure-storage';

await save('user_token', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');

// Met opties
await save('user_token', 'token_value', {
  service: 'com.myapp.tokens',
  accessGroup: 'group.myapp.shared'
});
```

### `get(key: string, options?: SecureStorageOptions): Promise<string | null>`

Haalt een waarde op uit secure storage.

**Parameters:**
- `key`: De identificatie string van de opgeslagen waarde
- `options`: Optionele configuratie opties

**Returns:**
- `Promise<string | null>`: De opgeslagen waarde of null als niet gevonden

**Throws:**
- `SecureStorageError`: Bij validatie fouten of keychain problemen

**Example:**
```typescript
import { get } from 'react-native-secure-storage';

const token = await get('user_token');
if (token) {
  console.log('Token gevonden:', token);
} else {
  console.log('Token niet gevonden');
}
```

### `remove(options?: SecureStorageOptions): Promise<void>`

Verwijdert alle data uit secure storage voor de gegeven service.

**Parameters:**
- `options`: Optionele configuratie opties

**Throws:**
- `SecureStorageError`: Bij keychain problemen

**Example:**
```typescript
import { remove } from 'react-native-secure-storage';

await remove();
console.log('Alle data verwijderd');
```

### `exists(key: string, options?: SecureStorageOptions): Promise<boolean>`

Controleert of een key bestaat in secure storage.

**Parameters:**
- `key`: De identificatie string om te controleren
- `options`: Optionele configuratie opties

**Returns:**
- `Promise<boolean>`: true als de key bestaat, false anders

**Throws:**
- `SecureStorageError`: Bij validatie fouten of keychain problemen

**Example:**
```typescript
import { exists } from 'react-native-secure-storage';

const hasToken = await exists('user_token');
if (hasToken) {
  console.log('Token bestaat');
}
```

## 🔧 Configuratie Opties

### `SecureStorageOptions`

```typescript
interface SecureStorageOptions {
  /** Service identifier voor keychain opslag */
  service?: string;
  
  /** Access group voor keychain sharing (iOS alleen) */
  accessGroup?: string;
  
  /** Toegankelijkheid niveau van keychain item */
  accessibility?: string;
}
```

**Standaard waarden:**
- `service`: `'com.mycompany.secure'`
- `accessGroup`: `undefined` (geen sharing)
- `accessibility`: `undefined` (systeem standaard)

## 🚨 Error Handling

De package gebruikt custom error types voor gedetailleerde foutafhandeling:

```typescript
import { SecureStorageError, SecureStorageErrorCode } from 'react-native-secure-storage';

try {
  await save('key', 'value');
} catch (error) {
  if (error instanceof SecureStorageError) {
    switch (error.code) {
      case SecureStorageErrorCode.INVALID_PARAMETER:
        console.log('Ongeldige parameter:', error.message);
        break;
      case SecureStorageErrorCode.KEYCHAIN_ERROR:
        console.log('Keychain fout:', error.message);
        break;
      case SecureStorageErrorCode.USER_CANCELLED:
        console.log('Gebruiker geannuleerd');
        break;
      default:
        console.log('Onbekende fout:', error.message);
    }
  }
}
```

### Error Codes

- `UNKNOWN`: Onbekende fout
- `KEYCHAIN_ERROR`: Keychain operatie gefaald
- `INVALID_PARAMETER`: Ongeldige parameter
- `OPERATION_FAILED`: Operatie gefaald
- `NOT_FOUND`: Item niet gevonden
- `ACCESS_DENIED`: Toegang geweigerd
- `BIOMETRY_NOT_AVAILABLE`: Biometrie niet beschikbaar
- `BIOMETRY_NOT_ENROLLED`: Biometrie niet ingesteld
- `USER_CANCELLED`: Gebruiker heeft geannuleerd

## 🛡️ Security Best Practices

1. **Gebruik sterke keys**: Gebruik unieke, moeilijk te raden keys
2. **Valideer data**: Controleer altijd de data voordat je deze opslaat
3. **Handle errors**: Implementeer proper error handling
4. **Gebruik access groups**: Voor data sharing tussen apps
5. **Test thoroughly**: Test op verschillende devices en OS versies

## 🧪 Testing

```bash
# Run alle tests
npm test

# Run tests met coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch
```

## 🔗 Gerelateerde Packages

- [react-native-secure-storage-pro](../react-native-secure-storage-pro): Pro versie met biometrische authenticatie, key rotation, en remote wipe
- [react-native-keychain](https://github.com/oblador/react-native-keychain): Onderliggende keychain implementatie

## 📝 Changelog

Zie [CHANGELOG.md](./CHANGELOG.md) voor een volledige lijst van wijzigingen.

## 🤝 Contributing

Zie [CONTRIBUTING.md](../../CONTRIBUTING.md) voor contributing guidelines.

## 📄 License

MIT License - zie [LICENSE](./LICENSE) voor details.

## 🆘 Support

- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/pasperfection/react-native-secure-storage-packages/issues)
- 💬 **Discussies**: [GitHub Discussions](https://github.com/pasperfection/react-native-secure-storage-packages/discussions)
- 📚 **Documentatie**: [Online docs](https://pasperfection.github.io/react-native-secure-storage-packages/)

---

**Gemaakt met ❤️ voor de React Native community**