deadmanswitch-encryption/README.md

Cross-platform encryption library for React Native and React web applications with password-based encryption

# @deadmanswitch/encryption

Cross-Platform Encryption Library

A lightweight, cross-platform encryption library that works seamlessly with both React Native and React web applications. Uses password-based encryption with PBKDF2 key derivation and AES-GCM encryption.

## Features

- **Cross-platform**: Works in React Native and React web/Next.js
- **Password-based encryption**: Secure PBKDF2 key derivation
- **AES-GCM encryption**: Strong encryption with built-in authentication
- **TypeScript support**: Full type definitions included
- **React Native**: Encryption and decryption
- **React Web**: Decryption only (as requested)

## Installation

```bash
npm install @deadmanswitch/encryption
```

For React Native, you'll also need to install the crypto dependency:

```bash
npm install react-native-quick-crypto
```

After installation, you'll need to complete the platform setup. For React Native 0.60+, run:

```bash
cd ios && pod install
```

## Usage

### React Native (Encryption + Decryption)

```typescript
import { encrypt, decrypt } from '@deadmanswitch/encryption';

// Encrypt data
const encryptData = async () => {
  const result = await encrypt('Hello, World!', {
    password: 'your-secure-password'
  });
  
  console.log('Encrypted:', result.encryptedData);
  console.log('Salt:', result.salt);
  console.log('IV:', result.iv);
  
  return result;
};

// Decrypt data
const decryptData = async (encryptionResult) => {
  const decrypted = await decrypt({
    password: 'your-secure-password',
    encryptedData: encryptionResult.encryptedData,
    salt: encryptionResult.salt,
    iv: encryptionResult.iv
  });
  
  console.log('Decrypted:', decrypted); // "Hello, World!"
  return decrypted;
};
```

### React Web/Next.js (Decryption Only)

```typescript
import { decrypt } from '@deadmanswitch/encryption';

// Decrypt data received from React Native
const decryptData = async () => {
  const decrypted = await decrypt({
    password: 'your-secure-password',
    encryptedData: 'encrypted-data-from-rn',
    salt: 'salt-from-rn',
    iv: 'iv-from-rn'
  });
  
  console.log('Decrypted:', decrypted);
  return decrypted;
};
```

## API Reference

### `encrypt(data: string, options: EncryptionOptions): Promise<EncryptionResult>`

Encrypts a string using password-based encryption.

**Parameters:**
- `data` - The string to encrypt
- `options` - Encryption options
  - `password` - The password to use for encryption
  - `iterations?` - Number of PBKDF2 iterations (default: 100000)
  - `keyLength?` - Key length in bits (default: 256)

**Returns:** Promise resolving to an `EncryptionResult` containing:
- `encryptedData` - Base64 encoded encrypted data
- `salt` - Base64 encoded salt
- `iv` - Base64 encoded initialization vector

### `decrypt(options: DecryptionOptions): Promise<string>`

Decrypts data using password-based decryption.

**Parameters:**
- `options` - Decryption options
  - `password` - The password used for encryption
  - `encryptedData` - Base64 encoded encrypted data
  - `salt` - Base64 encoded salt
  - `iv` - Base64 encoded initialization vector
  - `iterations?` - Number of PBKDF2 iterations (default: 100000)
  - `keyLength?` - Key length in bits (default: 256)

**Returns:** Promise resolving to the decrypted string

## Security Notes

- Uses PBKDF2 with 100,000 iterations by default
- Uses AES-GCM for authenticated encryption
- Generates random salt and IV for each encryption
- Password should be strong and stored securely
- Never hardcode passwords in your application

## Platform Detection

The library automatically detects the platform and uses the appropriate implementation:
- **React Native**: Uses `react-native-quick-crypto` for native performance
- **Web/Next.js**: Uses Web Crypto API

## TypeScript

Full TypeScript support is included with exported interfaces:

```typescript
import type { 
  EncryptionOptions, 
  EncryptionResult, 
  DecryptionOptions 
} from '@deadmanswitch/encryption';
```

## License

MIT