better-cipher/README.md

A secure encryption library with browser and Node.js support using AES-GCM

# Better Cipher

A secure encryption library with browser and Node.js support using AES-256-GCM.

## Features

- 🔒 AES-256-GCM encryption
- 🌐 Works in both Node.js and browser environments
- 🔄 Key rotation support
- 📦 Zero dependencies (uses platform native crypto APIs)
- 🎯 TypeScript support
- ✨ Simple API

## Installation

```bash
npm install better-cipher
# or
yarn add better-cipher
# or
pnpm add better-cipher
```

## Usage

### Node.js

```typescript
import { Cipher } from "better-cipher";

// Create a cipher instance with a 32-byte (64 hex characters) key
const cipher = new Cipher(
  "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
);

// Encrypt
const encrypted = await cipher.encrypt("Hello, World!");
// {
//   iv: '...',        // 24 characters (12 bytes in hex)
//   content: '...',   // encrypted data in hex
//   authTag: '...'    // authentication tag in hex
// }

// Decrypt
const decrypted = await cipher.decrypt(encrypted);
// 'Hello, World!'
```

### Browser

```typescript
import { Cipher } from "better-cipher";

// Same API as Node.js!
const cipher = new Cipher(
  "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
);

const encrypted = await cipher.encrypt("Hello, World!");
const decrypted = await cipher.decrypt(encrypted);
```

### Key Rotation

```typescript
import { Cipher } from 'better-cipher';

const oldKey = '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef';
const newKey = 'fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210';

// Create a rotator function
const rotator = Cipher.createRotator(oldKey, newKey);

// Re-encrypt data with new key
const oldEncrypted = /* ... previously encrypted data ... */;
const newEncrypted = await rotator(oldEncrypted);
```

## API Documentation

### `class Cipher`

#### Constructor

```typescript
constructor(secretKeyHex: string)
```

Creates a new Cipher instance.

- `secretKeyHex`: A 32-byte (64 hex characters) key in hexadecimal format.
- Throws if key is invalid (wrong length or non-hex characters).

#### Methods

##### `encrypt(text: string): Promise<Encrypted>`

Encrypts a string using AES-256-GCM.

- `text`: The string to encrypt (can be empty).
- Returns: Promise resolving to an `Encrypted` object.

##### `decrypt(encrypted: Encrypted): Promise<string>`

Decrypts previously encrypted data.

- `encrypted`: An `Encrypted` object from the `encrypt` method.
- Returns: Promise resolving to the original string.

##### `static createRotator(oldSecretKey: string, newSecretKey: string): (encrypted: Encrypted) => Promise<Encrypted>`

Creates a key rotation function.

- `oldSecretKey`: The current encryption key.
- `newSecretKey`: The new encryption key.
- Returns: A function that takes old encrypted data and returns newly encrypted data.

### Types

```typescript
interface Encrypted {
  iv: string; // Initialization vector (hex)
  content: string; // Encrypted content (hex)
  authTag: string; // Authentication tag (hex, Node.js only)
}
```

## Requirements

- Node.js >= 20.0.0
- Modern browsers with Web Crypto API support

## License

MIT