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

npm install ashcrypt

🧠 Usage

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

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<Buffer>

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<Buffer>

Encrypts a single chunk. Appends salt + iv + tag to encrypted content.

decrypt(buffer: Buffer): Promise<Buffer>

Decrypts a previously encrypted chunk. Extracts and uses the appended metadata.

📄 Class: Stream<Algorithm>

Provides stream-based encryption/decryption for large files.

Constructor

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:

[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 for details.