npm package: @fulroi/crypto-utils
Description: Crypto utilities and string helpers for Node.js applications
Author: FullRevenue Security Team
Latest version: 1.0.0

# @fulroi/crypto-utils

🔒 **Cryptographic utilities and string helpers for Node.js applications**

## 📦 Installation

```bash
npm install @fulroi/crypto-utils
```

## 🚀 Quick Start

```typescript
import { PasswordHash, SecureEncrypt, capitalize, normalize } from '@fulroi/crypto-utils';

// Hash passwords securely
const hash = await PasswordHash.hash('userPassword123');
const isValid = await PasswordHash.verify('userPassword123', hash);

// Encrypt/decrypt data
const encrypted = await SecureEncrypt.encrypt('sensitive data', 'secretKey');
const decrypted = await SecureEncrypt.decrypt(encrypted, 'secretKey');

// String utilities
const title = capitalize('hello world'); // "Hello World"
const slug = normalize('Título con Ácentos'); // "titulo-con-acentos"
```

## 📚 API Reference

### Password Security

#### `PasswordHash.hash(password: string): Promise<string>`
Securely hash a password using bcrypt with automatic salt generation.

#### `PasswordHash.verify(password: string, hash: string): Promise<boolean>`
Verify a password against its hash.

#### `PasswordHash.needsRehash(hash: string): boolean`
Check if a hash needs updating to stronger security parameters.

### Data Encryption

#### `SecureEncrypt.encrypt(text: string, secret: string): Promise<string>`
Encrypt data using AES-256-GCM with random IV and salt for each operation.

#### `SecureEncrypt.decrypt(encryptedData: string, secret: string): Promise<string>`
Decrypt data that was encrypted with `SecureEncrypt.encrypt()`.

### String Utilities

#### `capitalize(str: string): string`
Capitalizes the first letter of each word in a string.

```typescript
capitalize('hello world') // "Hello World"
```

#### `normalize(str: string): string`
Normalizes a string by removing accents, replacing special characters with hyphens, and converting to lowercase.

```typescript
normalize('Título con Ácentos!') // "titulo-con-acentos"
```

## 🔐 Security Features

- **bcrypt password hashing** with configurable cost factor (12)
- **AES-256-GCM encryption** with authenticated encryption
- **Random IV and salt** for each encryption operation
- **Input validation** and error handling
- **TypeScript support** with full type definitions

## 📄 Examples

### Password Management
```typescript
import { PasswordHash } from '@fulroi/crypto-utils';

// Registration
const userPassword = 'userInput123';
const hashedPassword = await PasswordHash.hash(userPassword);
// Store hashedPassword in database

// Login
const loginPassword = 'userInput123';
const isValidPassword = await PasswordHash.verify(loginPassword, hashedPassword);
if (isValidPassword) {
    // User authenticated
}
```

### Data Encryption
```typescript
import { SecureEncrypt } from '@fulroi/crypto-utils';

const sensitiveData = 'Credit card: 4111-1111-1111-1111';
const secretKey = process.env.ENCRYPTION_KEY;

// Encrypt
const encrypted = await SecureEncrypt.encrypt(sensitiveData, secretKey);
// Store encrypted data

// Decrypt
const decrypted = await SecureEncrypt.decrypt(encrypted, secretKey);
console.log(decrypted); // 'Credit card: 4111-1111-1111-1111'
```

### String Processing
```typescript
import { capitalize, normalize } from '@fulroi/crypto-utils';

// Title formatting
const title = capitalize('product management system'); // "Product Management System"

// URL-friendly slugs
const slug = normalize('Café & Restaurante São Paulo'); // "cafe-restaurante-sao-paulo"
```

## ⚙️ Requirements

- Node.js 14 or higher
- TypeScript 4.0+ (for TypeScript projects)

## 📝 License

MIT

## 🤝 Contributing

Contributions, issues and feature requests are welcome!