https://github.com/ashu11-a/ashcrypt
Files protected with encryption
https://github.com/ashu11-a/ashcrypt
aes aes-256 aes-cipher aes-encryption aes-gcm asynchronous-crypto buffer crypto crypto-library crypto-tools cryptography encryption gcm node-aes node-crypto nodejs pbkdf2 stream-encryption typescript
Last synced: about 1 month ago
JSON representation
Files protected with encryption
- Host: GitHub
- URL: https://github.com/ashu11-a/ashcrypt
- Owner: Ashu11-A
- License: mit
- Created: 2024-04-07T00:16:54.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-21T10:21:34.000Z (about 1 year ago)
- Last Synced: 2025-10-11T10:12:07.624Z (8 months ago)
- Topics: aes, aes-256, aes-cipher, aes-encryption, aes-gcm, asynchronous-crypto, buffer, crypto, crypto-library, crypto-tools, cryptography, encryption, gcm, node-aes, node-crypto, nodejs, pbkdf2, stream-encryption, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/ashcrypt
- Size: 27.3 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# AshCrypt
---
## 📃 Description
**AshCrypt** is a modular and efficient encryption library for handling large files using the **AES-GCM** encryption algorithm. It provides chunked encryption and decryption support using streams for memory-efficient processing, suitable for secure file handling and transmission.
The library divides files into configurable chunks (default 512 KB), encrypts each chunk separately, and appends essential metadata (salt, IV, tag) to each chunk.
---
## ⚙️ Features
- 🔐 AES-GCM encryption (128, 192, or 256-bit)
- 🧩 Configurable chunk size (default: 512KB)
- 📁 Stream-based I/O for large files
- 🔄 Parallel processing support for better performance
- 📦 Easy integration and usage via typed API
---
## 🚀 Installation
```bash
npm install ashcrypt
```
---
## 🧠 Usage
```ts
import { AES, Stream } from 'ashcrypt';
const aes = new AES({ secret: 'my-very-secure-password' });
const stream = new Stream({ algorithm: aes });
// Encrypting a file
stream.read('input.txt', 'encrypt')
.pipe(stream.write('output.enc'))
.on('finish', () => {
// Decrypting a file
stream.read('output.enc', 'decrypt')
.pipe(stream.write('decrypted.txt'));
})
```
---
## 🔐 Class: `AES`
Handles key derivation and encryption/decryption of buffers.
### Constructor
```ts
new AES({ secret, chunkSize, algorithm, iterations });
```
- `secret`: Password or passphrase
- `chunkSize`: (Optional): Default: 512 * 1000 (512KB)
- `algorithm`: (Optional): Default: 'aes-256-gcm'
- `iterations`: (Optional): Default: 100000 (PBKDF2 iterations)
### `getKey(salt: Buffer): Promise`
Derives a key from the given salt using PBKDF2.
### `getChunkSize(baseChunkSize: number): number`
Returns the final size of a chunk after encryption (includes metadata).
### `encrypt(buffer: Buffer): Promise`
Encrypts a single chunk. Appends `salt + iv + tag` to encrypted content.
### `decrypt(buffer: Buffer): Promise`
Decrypts a previously encrypted chunk. Extracts and uses the appended metadata.
---
## 📄 Class: `Stream`
Provides stream-based encryption/decryption for large files.
### Constructor
```ts
new Stream({ algorithm, maxParallel });
```
- `algorithm`: Instance of AES (or compatible)
- `maxParallel` (optional): Number of parallel chunks to process (default: 1)
### `create(type: "encrypt" | "decrypt"): Transform`
Creates a transform stream for encryption or decryption.
### `read(path: string, type: "encrypt" | "decrypt"): Transform`
Returns a read stream piped through transformation (encryption/decryption).
### `write(path: string): WriteStream`
Returns a write stream to save the final output.
---
## 📦 Chunk Format
Each chunk is encoded as:
```plaintext
[salt (16–32B)][IV (12B)][Auth Tag (16B)][Encrypted Data]
```
- **Salt**: Random bytes used for PBKDF2
- **IV**: Initialization vector
- **Auth Tag**: AES-GCM tag for integrity
- **Encrypted Data**: Ciphertext of the original chunk
---
## 📜 License
Licensed under the MIT License. See [LICENSE](./LICENSE) for details.
---
Made by Matheus Nilton Biolowons