securecrypt/Readme.md

SecureCrypt: High-performance Node.js encryption library. Provides AES-256-GCM encryption, PBKDF2-based key derivation, secure file & text encryption, password generation, and multi-threaded processing for maximum speed and security.

# SecureCrypt

SecureCrypt is a **high-performance encryption library for Node.js**, designed for developers who need fast, robust encryption and secure password handling. It supports AES-256-GCM encryption, PBKDF2 password-based key derivation, file & text encryption, secure password generation, multi-threaded file processing, and file metadata verification.

---


## Features

- **AES-256-GCM Encryption**: Authenticated encryption for text and files.  
- **PBKDF2 Key Derivation**: Securely derive keys from passwords with configurable iterations.  
- **File Encryption**: Encrypt large files with progress reporting.  
- **Text Encryption**: Safely encrypt and decrypt strings.  
- **Secure Password Generation**: Generate strong, customizable random passwords.  
- **Password Strength Validation**: Check passwords for length, complexity, and repeated characters.  
- **Multi-threaded File Processing**: Encrypt multiple files in parallel using worker threads.  
- **File Metadata & Info**: Verify if a file is encrypted and gather metadata.  
- **Secure File Wiping**: Overwrite files with random data before deletion.

> ⚠️ The **benchmark** feature exists in the library but does **not work reliably** and may give inaccurate results.

---


## Installation

```bash
npm install securecrypt
# or using yarn
yarn add securecrypt
````

---


## Usage

### Import Library

```javascript
const SecureCrypt = require('securecrypt');
```

---


### Text Encryption & Decryption

```javascript
const password = 'StrongPassword123!';
const message = 'Hello, SecureCrypt!';

// Encrypt
const encrypted = SecureCrypt.encryptText(message, password);
console.log('Encrypted Data:', encrypted.encryptedData);

// Decrypt
const decrypted = SecureCrypt.decryptText(encrypted.encryptedData, password);
if (decrypted.success) {
    console.log('Decrypted Text:', decrypted.decryptedText);
} else {
    console.error('Decryption Failed:', decrypted.error);
}
```

---


### File Encryption & Decryption

```javascript
const inputFile = './example.txt';
const encryptedFile = './example.txt.secrypt';
const decryptedFile = './example_decrypted.txt';

// Encrypt file
SecureCrypt.encryptFile(inputFile, encryptedFile, password, {
    onProgress: (progress) => console.log(`Encrypting: ${progress.percentage.toFixed(2)}%`)
}).then(result => {
    console.log('File encrypted successfully', result);

    // Decrypt file
    return SecureCrypt.decryptFile(encryptedFile, decryptedFile, password, {
        onProgress: (progress) => console.log(`Decrypting: ${progress.percentage.toFixed(2)}%`)
    });
}).then(result => {
    console.log('File decrypted successfully', result);
}).catch(err => {
    console.error(err);
});
```

---


### Generate Secure Passwords

```javascript
const password = SecureCrypt.generateSecurePassword(16);
console.log('Generated Password:', password);
```

---


### Validate Password Strength

```javascript
const result = SecureCrypt.validatePassword('WeakPass123');
console.log(result);

/*
Example output:
{
  isValid: false,
  score: 3,
  feedback: ["Password should contain special characters"],
  strength: "Weak"
}
*/
```

---


### Check if File is Encrypted

```javascript
if (SecureCrypt.isEncryptedFile('./example.txt.secrypt')) {
    console.log('File is encrypted with SecureCrypt.');
}
```

---


### Get File Info

```javascript
const info = SecureCrypt.getFileInfo('./example.txt.secrypt');
console.log(info);

/*
Example output:
{
  path: './example.txt.secrypt',
  size: 12345,
  isFile: true,
  encrypted: true,
  algorithm: 'aes-256-gcm',
  iterations: 100000,
  encryptedSize: 12300,
  created: 2025-09-14T00:00:00.000Z,
  modified: 2025-09-14T00:01:00.000Z,
}
*/
```

---


### Securely Wipe a File

```javascript
SecureCrypt.secureWipeFile('./secret.txt', 3)
    .then(() => console.log('File securely wiped'))
    .catch(err => console.error(err));
```

---


### Multi-threaded File Encryption

```javascript
const files = ['./file1.txt', './file2.txt'];
SecureCrypt.encryptFilesParallel(files, password, { workers: 2, outputDir: './encrypted' })
    .then(results => console.log('Parallel encryption results:', results))
    .catch(err => console.error(err));
```

---


### System Information

```javascript
console.log(SecureCrypt.getSystemInfo());

/*
Example output:
{
  platform: 'win32',
  architecture: 'x64',
  cpus: 8,
  totalMemory: '16384MB',
  freeMemory: '8192MB',
  nodeVersion: 'v20.0.0',
  recommendedChunkSize: 65536,
  version: '0.x.x'
}
*/
```

---


## License

MIT © 2025 [Bluezly](https://www.bluezly.exid.me)