wh-encrypt-api/README.md

Cross-platform encryption library providing consistent AES-256-GCM encryption for Node.js and Browser environments

# WH Encrypt API - Node.js Package

Cross-platform encryption library providing consistent AES-256-GCM encryption for Node.js and Browser environments with full compatibility with C# implementation.

## 🚀 Features

- **AES-256-GCM Encryption**: Industry-standard authenticated encryption with integrity verification
- **PBKDF2 Key Derivation**: Secure key derivation with 100,000 iterations using SHA-256
- **Cross-Platform Compatible**: Full interoperability with C# implementation
- **Browser Support**: Web Crypto API compatibility for frontend applications
- **TypeScript Support**: Complete type definitions included
- **Zero Dependencies**: Uses Node.js built-in crypto module
- **Security Validated**: Tampering detection and key separation

## 📦 Installation

```bash
npm install wh-encrypt-api
```

## 💻 Usage Examples

### Node.js Backend

```javascript
const { createEncryption } = require("wh-encrypt-api");

// Initialize encryption service
const encryption = createEncryption("your-secret-key");

// Encrypt data (any JSON-serializable object)
const userData = { id: 123, name: "John Doe", active: true };
const encrypted = encryption.encryptData(userData);

// Decrypt data
const decrypted = encryption.decryptData(encrypted);
console.log(decrypted); // { id: 123, name: 'John Doe', active: true }
```

### Browser Frontend

```javascript
import { createBrowserEncryption } from "wh-encrypt-api";

// Initialize browser-compatible encryption
const encryption = createBrowserEncryption("your-secret-key");

// Encrypt data (async in browser)
const userData = { id: 123, name: "John Doe", active: true };
const encrypted = await encryption.encryptData(userData);

// Decrypt data (async in browser)
const decrypted = await encryption.decryptData(encrypted);
console.log(decrypted); // { id: 123, name: 'John Doe', active: true }
```

### TypeScript

```typescript
import { createEncryption, EncryptionInstance } from "wh-encrypt-api";

interface UserData {
  id: number;
  name: string;
  active: boolean;
}

const encryption: EncryptionInstance = createEncryption("your-secret-key");
const userData: UserData = { id: 123, name: "John Doe", active: true };

const encrypted: string = encryption.encryptData(userData);
const decrypted: UserData = encryption.decryptData(encrypted);
```

## 🔗 Cross-Platform Compatibility

This Node.js package is fully compatible with the C# implementation:

```javascript
// Node.js: Encrypt data
const nodeEncryption = createEncryption("shared-secret");
const encrypted = nodeEncryption.encryptData({
  message: "Hello from Node.js!",
});

// The encrypted data can be decrypted by the C# implementation:
// using var csharpEncryption = new EncryptionService("shared-secret");
// var decrypted = csharpEncryption.DecryptData<dynamic>(encryptedFromNodejs);
```

## 📚 API Reference

### `createEncryption(secretKey, salt?)`

Creates an encryption instance for Node.js environments.

**Parameters:**

- `secretKey` (string): The secret key for encryption/decryption
- `salt` (string, optional): Salt for key derivation (default: 'encryption-salt')

**Returns:** `EncryptionInstance` object with encryption methods

### `createBrowserEncryption(secretKey, salt?)`

Creates an encryption instance for browser environments using Web Crypto API.

**Parameters:**

- `secretKey` (string): The secret key for encryption/decryption
- `salt` (string, optional): Salt for key derivation (default: 'encryption-salt')

**Returns:** `BrowserEncryptionInstance` object with async encryption methods

### `EncryptionInstance.encryptData(data)`

Encrypts any JSON-serializable data using AES-256-GCM.

**Parameters:**

- `data` (any): Data to encrypt (will be JSON serialized)

**Returns:** Base64 encoded encrypted string

### `EncryptionInstance.decryptData(encryptedData)`

Decrypts data encrypted with `encryptData`.

**Parameters:**

- `encryptedData` (string): Base64 encoded encrypted data

**Returns:** Original decrypted data

## 🔒 Security Specifications

### Encryption Algorithm

- **Cipher**: AES-256-GCM (Galois/Counter Mode)
- **Key Size**: 256 bits (32 bytes)
- **IV Size**: 96 bits (12 bytes) - randomly generated per operation
- **Authentication Tag**: 128 bits (16 bytes)
- **Additional Auth Data**: "WH-Encryption-v1" for integrity verification

### Key Derivation

- **Algorithm**: PBKDF2 with HMAC-SHA256
- **Iterations**: 100,000 (configurable)
- **Salt**: "encryption-salt" (default, configurable)
- **Output**: 256-bit derived key

### Data Format

All encrypted data follows this format (Base64 encoded):

```
[IV: 12 bytes] + [Auth Tag: 16 bytes] + [Ciphertext: variable]
```

## 🧪 Testing

```bash
# Run unit tests
npm test

# Generate coverage report
npm run test:coverage

# Run cross-platform compatibility tests
npm run compatibility

# Validate library integrity
npm run validate
```

## 📈 Performance

Typical performance characteristics:

- **Node.js**: ~20-30 operations/second for 1KB payloads
- **Browser**: ~15-25 operations/second for 1KB payloads
- **Memory**: Minimal memory footprint

## 🔧 Environment Support

### Node.js

- **Versions**: Node.js 16.0.0+
- **Platforms**: Windows, macOS, Linux
- **Architectures**: x64, ARM64

### Browser

- **Modern browsers** with Web Crypto API support
- **Chrome**: 37+
- **Firefox**: 34+
- **Safari**: 7+
- **Edge**: 12+

## 🐛 Troubleshooting

### Common Issues

**Error: "crypto module not found"**

- Ensure you're using Node.js 16+
- For browser environments, use `createBrowserEncryption()`

**Error: "Invalid encrypted data"**

- Verify the secret key matches between encryption and decryption
- Check that the encrypted data hasn't been modified or corrupted

**Performance Issues**

- Consider implementing caching for frequently used encryption instances
- Use appropriate payload sizes (recommended < 10MB)

## 📋 Version Compatibility

| Node.js Version | Package Version | Status           |
| --------------- | --------------- | ---------------- |
| 16.x            | 1.0.0+          | ✅ Supported     |
| 18.x            | 1.0.0+          | ✅ Supported     |
| 20.x            | 1.0.0+          | ✅ Supported     |
| 14.x            | -               | ❌ Not supported |

## 🤝 Contributing

See the main repository [README.md](../README.md) for contribution guidelines.

## 📄 License

MIT License
Copyright © 2025 Duong Tran Quang. All rights reserved.

See [LICENSE](./LICENSE) for full license terms.

## 👥 Authors

**Author**: Duong Tran Quang
**Email**: baymax.contact@gmail.com
**GitHub**: https://github.com/DTDucas

## 🆘 Support

For technical support:

1. Check the documentation and examples above
2. Review test files for additional usage patterns
3. Create an issue on GitHub or email baymax.contact@gmail.com
4. Ensure you're using the latest version

## 🔗 Related Packages

- **C# Package**: `WH.Encryption` - NuGet package for .NET applications
- **Main Repository**: [wh-encrypt-api](https://github.com/DTDucas/wh-encrypt-api)

---

**Note**: This package is open source and available for use in any project under the MIT license.