wilcocrypt 2.1.1 → 2.2.0

package/src/wilcocrypt.js

@@ -1,7 +1,7 @@
 import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from 'crypto';
-import { encode as msgpack_encode, decode as msgpack_decode } from 'notepack.io';
-import { gzipSync, gunzipSync } from 'zlib';
-import { readFileSync, writeFileSync } from 'fs';
+import { gzipSync, gunzipSync, createGzip, createGunzip } from 'zlib';
+import { readFileSync, writeFileSync, createReadStream, createWriteStream, promises as fsPromises } from 'fs';
+import { pipeline } from 'stream/promises';
 
 /**
  * Main WilcoCrypt namespace.
@@ -25,7 +25,7 @@ class WilcoCryptError extends Error {
    * @param {string} message - Human-readable error message
    * @param {string} [code=WILCOCRYPT_ERROR] - Machine-readable error code
    */
-  constructor(message, code = 'WILCOCRYPT_ERROR') {
+  constructor (message, code = 'WILCOCRYPT_ERROR') {
     super(message);
     this.name = 'WilcoCryptError';
     this.code = code;
@@ -47,7 +47,7 @@ wilcocrypt._.WilcoCryptError = WilcoCryptError;
  * Must match exactly during decryption.
  * @type {string}
  */
-wilcocrypt._.VERSION = '2.1.1';
+wilcocrypt._.VERSION = '2.2.0';
 
 /**
  * Minimum allowed password length.
@@ -55,6 +55,12 @@ wilcocrypt._.VERSION = '2.1.1';
  */
 wilcocrypt._.MIN_PASSWORD_LENGTH = 6;
 
+/**
+ * Internal header for encrypted payloads.
+ * @type {Buffer}
+ */
+wilcocrypt._.HEADER = Buffer.from([23, 9, 12, 3, 15, 3, 18, 25, 16, 20]);
+
 /* =========================
    Internal helpers
 ========================= */
@@ -76,7 +82,7 @@ wilcocrypt._.assertKeyAndIv = function (key, iv) {
 
   if (!Buffer.isBuffer(iv) || iv.length !== 12) {
     throw new WilcoCryptError(
-      'Invalid IV (expected 12-byte Buffer for GCM)',
+      'Invalid IV (expected 12-byte Buffer)',
       'INVALID_IV'
     );
   }
@@ -145,21 +151,21 @@ wilcocrypt._.encryptData = function (plainData, key, iv) {
 /**
  * Decrypts AES-256-GCM encrypted data.
  *
- * @param {string} cipherHex
- * @param {string} authTagHex
+ * @param {Buffer} cipherBuffer
+ * @param {Buffer} authTagBuffer
  * @param {Buffer} key
  * @param {Buffer} iv
  * @returns {Buffer}
  */
-wilcocrypt._.decryptData = function (cipherHex, authTagHex, key, iv) {
+wilcocrypt._.decryptData = function (cipherBuffer, authTagBuffer, key, iv) {
   wilcocrypt._.assertKeyAndIv(key, iv);
 
   try {
     const decipher = createDecipheriv('aes-256-gcm', key, iv);
-    decipher.setAuthTag(Buffer.from(authTagHex, 'hex'));
+    decipher.setAuthTag(authTagBuffer);
 
     return Buffer.concat([
-      decipher.update(Buffer.from(cipherHex, 'hex')),
+      decipher.update(cipherBuffer),
       decipher.final()
     ]);
   } catch {
@@ -177,90 +183,77 @@ wilcocrypt._.decryptData = function (cipherHex, authTagHex, key, iv) {
 /**
  * Encrypts data using password-based AES-256-GCM.
  *
+ * Output format:
+ * [HEADER (10 bytes)] + [VERSION (dynamic)] + [salt (16)] + [iv (12)] + [ciphertext] + [authTag (16)]
+ *
  * @param {Buffer} plaindata - Raw data to encrypt
  * @param {string} password - Password used for key derivation
  * @param {boolean} [gzip=true] - Whether to compress data before encryption
- * @returns {Buffer} MessagePack-encoded encrypted payload
+ * @returns {Buffer} Binary-encoded encrypted payload
  * @throws {WilcoCryptError} If password is invalid
  */
 wilcocrypt.encryptData = function (plaindata, password, gzip = true) {
-    wilcocrypt._.assertPassword(password);
+  wilcocrypt._.assertPassword(password);
 
-    let gzipData;
-    if (gzip) {
-        gzipData = gzipSync(plaindata);
-    } else {
-        gzipData = plaindata;
-    }
+  const gzipData = gzip ? gzipSync(plaindata) : plaindata;
+  const iv = randomBytes(12);
+  const salt = randomBytes(16);
 
-    const iv = randomBytes(12);
-    const salt = randomBytes(16);
+  const key = scryptSync(password, salt, 32);
 
-    const key = scryptSync(password, salt, 32);
+  const { ciphertext, authTag } = wilcocrypt._.encryptData(gzipData, key, iv);
+  const versionBuf = Buffer.from(wilcocrypt._.VERSION);
 
-    const { ciphertext, authTag } = wilcocrypt._.encryptData(gzipData, key, iv);
-
-    const envelope = {
-        payload: ciphertext.toString('hex'),
-        authTag: authTag.toString('hex'),
-        salt: salt.toString('hex'),
-        iv: iv.toString('hex'),
-        version: wilcocrypt._.VERSION
-    };
-
-    return msgpack_encode(envelope);
+  return Buffer.concat([
+    wilcocrypt._.HEADER, // 10 bytes
+    versionBuf, // dynamic
+    salt, // 16 bytes
+    iv, // 12 bytes
+    ciphertext, // variable
+    authTag // 16 bytes (at the end for streaming compatibility)
+  ]);
 };
 
 /**
  * Decrypts encrypted data using password-based AES-256-GCM.
  *
- * @param {Buffer} encryptedData - MessagePack-encoded encrypted payload
+ * Validates internal header and version, then extracts:
+ * salt, iv, authTag and ciphertext from the binary payload.
+ *
+ * @param {Buffer} encryptedBuffer - Binary-encoded encrypted payload
  * @param {string} password - Password used for decryption
  * @param {boolean} [gzip=true] - Whether to decompress after decryption
  * @returns {Buffer} Decrypted raw data
- * @throws {WilcoCryptError} On invalid format, wrong password, version mismatch, or decompression failure
+ * @throws {WilcoCryptError} On invalid header, version mismatch, wrong password, or corrupted data
  */
-wilcocrypt.decryptData = function (encryptedData, password, gzip = true) {
-    wilcocrypt._.assertPassword(password);
-    
-    let envelope;
-    try {
-        envelope = msgpack_decode(encryptedData);
-    } catch {
-        throw new WilcoCryptError(
-            'Invalid encrypted data format (not MessagePack)',
-            'INVALID_FORMAT'
-        );
-    }
+wilcocrypt.decryptData = function (encryptedBuffer, password, gzip = true) {
+  wilcocrypt._.assertPassword(password);
 
-    if (envelope.version !== wilcocrypt._.VERSION) {
-        throw new WilcoCryptError(
-            `Version mismatch (expected ${wilcocrypt._.VERSION}, got ${envelope.version})`,
-            'VERSION_MISMATCH'
-        );
-    }
+  const versionBuf = Buffer.from(wilcocrypt._.VERSION);
+  let offset = 0;
 
-    const key = scryptSync(password, Buffer.from(envelope.salt, 'hex'), 32);
+  const fileHeader = encryptedBuffer.subarray(offset, offset += wilcocrypt._.HEADER.length);
+  if (!fileHeader.equals(wilcocrypt._.HEADER)) {
+    throw new WilcoCryptError('Invalid WilcoCrypt header', 'INVALID_HEADER');
+  }
 
-    const decrypted = wilcocrypt._.decryptData(
-        envelope.payload,
-        envelope.authTag,
-        key,
-        Buffer.from(envelope.iv, 'hex')
-    );
+  const fileVersion = encryptedBuffer.subarray(offset, offset += versionBuf.length);
+  if (!fileVersion.equals(versionBuf)) {
+    throw new WilcoCryptError('Version mismatch', 'VERSION_MISMATCH');
+  }
 
-    try {
-        if (gzip) {
-            return gunzipSync(decrypted);
-        } else {
-            return decrypted;
-        }
-    } catch {
-        throw new WilcoCryptError(
-            'Decryption succeeded but decompression failed (data may be corrupted or not compressed)',
-            'DECOMPRESSION_FAILED'
-        );
-    }
+  const salt = encryptedBuffer.subarray(offset, offset += 16);
+  const iv = encryptedBuffer.subarray(offset, offset += 12);
+
+  // authTag are the last 16 bytes; ciphertext is everything in between
+  const authTag = encryptedBuffer.subarray(encryptedBuffer.length - 16);
+  const ciphertext = encryptedBuffer.subarray(offset, encryptedBuffer.length - 16);
+
+  const key = scryptSync(password, salt, 32);
+
+  const decrypted = wilcocrypt._.decryptData(ciphertext, authTag, key, iv);
+
+  return gzip ? gunzipSync(decrypted) : decrypted;
 };
 
 /**
@@ -273,30 +266,157 @@ wilcocrypt.decryptData = function (encryptedData, password, gzip = true) {
  * @throws {WilcoCryptError} If password is invalid
  */
 wilcocrypt.encryptFile = function (filePath, password, gzip = true) {
-    const fileData = readFileSync(filePath);
-    const encryptedData = wilcocrypt.encryptData(fileData, password, gzip);
-    writeFileSync(`${filePath}.enc`, encryptedData);
+  const fileData = readFileSync(filePath);
+  const encryptedData = wilcocrypt.encryptData(fileData, password, gzip);
+  writeFileSync(`${filePath}.enc`, encryptedData);
 };
 
 /**
  * Decrypts an encrypted `.enc` file.
  *
+ * If `outputPath` is provided, the decrypted data is written to that file
+ * and `undefined` is returned. Otherwise the decrypted Buffer is returned.
+ *
  * @param {string} filePath - Path to the `.enc` file
  * @param {string} password - Password used for decryption
+ * @param {string|boolean} [outputPath] - Optional path to write decrypted output to.
+ *   If omitted (or `true`/`false`), the function returns the decrypted Buffer instead.
  * @param {boolean} [gzip=true] - Whether to decompress after decryption
- * @returns {Buffer} Decrypted file contents
+ * @returns {Buffer|undefined} Decrypted file contents, or undefined if outputPath was given
  * @throws {WilcoCryptError} If file extension is invalid or decryption fails
  */
-wilcocrypt.decryptFile = function (filePath, password, gzip = true) {
-    if (!filePath.endsWith('.enc')) {
-        throw new WilcoCryptError(
-            'Invalid file extension (expected .enc)',
-            'INVALID_FILE_EXTENSION'
-        );
-    }
+wilcocrypt.decryptFile = function (filePath, password, outputPath, gzip = true) {
+  // Support legacy 3-argument form: decryptFile(filePath, password, gzip?)
+  if (typeof outputPath === 'boolean') {
+    gzip = outputPath;
+    outputPath = undefined;
+  }
+
+  if (!filePath.endsWith('.enc')) {
+    throw new WilcoCryptError(
+      'Invalid file extension (expected .enc)',
+      'INVALID_FILE_EXTENSION'
+    );
+  }
+
+  const encryptedData = readFileSync(filePath);
+  const decrypted = wilcocrypt.decryptData(encryptedData, password, gzip);
+
+  if (outputPath) {
+    writeFileSync(outputPath, decrypted);
+    return;
+  }
+
+  return decrypted;
+};
+
+/**
+ * Encrypts a file using streams and writes the result to `outputPath`.
+ * Memory-efficient alternative to `encryptFile` for large files.
+ *
+ * Output format:
+ * [HEADER] + [VERSION] + [salt (16)] + [iv (12)] + [ciphertext] + [authTag (16)]
+ *
+ * @param {string} inputPath - Path to the file to encrypt
+ * @param {string} outputPath - Path to write the encrypted output to
+ * @param {string} password - Password used for key derivation
+ * @param {boolean} [gzip=true] - Whether to compress data before encryption
+ * @returns {Promise<void>}
+ * @throws {WilcoCryptError} If password is invalid
+ */
+wilcocrypt.encryptFileStream = async function (inputPath, outputPath, password, gzip = true) {
+  wilcocrypt._.assertPassword(password);
+
+  const salt = randomBytes(16);
+  const iv = randomBytes(12);
+  const key = scryptSync(password, salt, 32);
+  const versionBuf = Buffer.from(wilcocrypt._.VERSION);
+
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const writeStream = createWriteStream(outputPath);
+
+  writeStream.write(wilcocrypt._.HEADER);
+  writeStream.write(versionBuf);
+  writeStream.write(salt);
+  writeStream.write(iv);
+
+  const pipelineSteps = [createReadStream(inputPath)];
+  if (gzip) pipelineSteps.push(createGzip());
+  pipelineSteps.push(cipher);
+  pipelineSteps.push(writeStream);
+
+  // end: false so we can still append the authTag after the pipeline finishes
+  await pipeline(...pipelineSteps, { end: false });
+  writeStream.end(cipher.getAuthTag());
+};
+
+/**
+ * Decrypts an encrypted `.enc` file using streams.
+ * Memory-efficient alternative to `decryptFile` for large files.
+ * Cleans up the output file automatically if decryption or integrity check fails.
+ *
+ * @param {string} inputPath - Path to the encrypted `.enc` file
+ * @param {string} outputPath - Path to write the decrypted output to
+ * @param {string} password - Password used for decryption
+ * @param {boolean} [gzip=true] - Whether to decompress after decryption
+ * @returns {Promise<void>}
+ * @throws {WilcoCryptError} On invalid header, version mismatch, or decryption/integrity failure
+ */
+wilcocrypt.decryptFileStream = async function (inputPath, outputPath, password, gzip = true) {
+  wilcocrypt._.assertPassword(password);
+
+  const handle = await fsPromises.open(inputPath, 'r');
+  const versionBuf = Buffer.from(wilcocrypt._.VERSION);
+
+  const headLen = wilcocrypt._.HEADER.length;
+  const verLen = versionBuf.length;
+
+  const headerCheck = Buffer.alloc(headLen);
+  const versionCheck = Buffer.alloc(verLen);
+  const salt = Buffer.alloc(16);
+  const iv = Buffer.alloc(12);
+
+  let currentPos = 0;
+  await handle.read(headerCheck, 0, headLen, currentPos); currentPos += headLen;
+  await handle.read(versionCheck, 0, verLen, currentPos); currentPos += verLen;
+  await handle.read(salt, 0, 16, currentPos); currentPos += 16;
+  await handle.read(iv, 0, 12, currentPos); currentPos += 12;
+
+  if (!headerCheck.equals(wilcocrypt._.HEADER)) {
+    await handle.close();
+    throw new WilcoCryptError('Invalid WilcoCrypt header', 'INVALID_HEADER');
+  }
+
+  if (!versionCheck.equals(versionBuf)) {
+    await handle.close();
+    throw new WilcoCryptError('Version mismatch', 'VERSION_MISMATCH');
+  }
+
+  const stats = await handle.stat();
+  const authTag = Buffer.alloc(16);
+  await handle.read(authTag, 0, 16, stats.size - 16);
+
+  const key = scryptSync(password, salt, 32);
+  const decipher = createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(authTag);
+
+  const pipelineSteps = [createReadStream(inputPath, { start: currentPos, end: stats.size - 17 })];
+  pipelineSteps.push(decipher);
+  if (gzip) pipelineSteps.push(createGunzip());
+  pipelineSteps.push(createWriteStream(outputPath));
+
+  try {
+    await pipeline(...pipelineSteps);
+  } catch {
+    await handle.close();
+    await fsPromises.unlink(outputPath);
+    throw new WilcoCryptError(
+      'Decryption failed (invalid password, corrupted data, or tampered file)',
+      'DECRYPTION_FAILED'
+    );
+  }
 
-    const encryptedData = readFileSync(filePath);
-    return wilcocrypt.decryptData(encryptedData, password, gzip);
+  await handle.close();
 };
 
 export default wilcocrypt;

package/types/wilcocrypt.d.ts

@@ -1,28 +1,60 @@
 /// <reference types="node" />
 
+/**
+ * Custom error class for all WilcoCrypt-specific errors.
+ */
 export class WilcoCryptError extends Error {
   code: string;
-  constructor(message: string, code?: string);
-}
 
-export interface EncryptResultEnvelope {
-  payload: string;
-  authTag: string;
-  salt: string;
-  iv: string;
-  version: string;
+  /**
+   * @param message Human-readable error message
+   * @param code Machine-readable error code (default: WILCOCRYPT_ERROR)
+   */
+  constructor(message: string, code?: string);
 }
 
+/**
+ * Internal helper namespace used by WilcoCrypt.
+ */
 export interface InternalNamespace {
+  /**
+   * WilcoCrypt version (must match during decryption).
+   */
   VERSION: string;
+
+  /**
+   * Minimum allowed password length.
+   */
   MIN_PASSWORD_LENGTH: number;
 
+  /**
+   * Internal header used to identify valid WilcoCrypt payloads.
+   */
+  HEADER: Buffer;
+
+  /**
+   * Internal error class used by WilcoCrypt.
+   */
   WilcoCryptError: typeof WilcoCryptError;
 
+  /**
+   * Validates AES-256-GCM key and IV.
+   */
   assertKeyAndIv(key: Buffer, iv: Buffer): void;
+
+  /**
+   * Validates password strength.
+   */
   assertPassword(password: string): void;
+
+  /**
+   * Constant-time buffer comparison.
+   */
   constantTimeEqual(a: Buffer, b: Buffer): boolean;
 
+  /**
+   * Encrypts raw data using AES-256-GCM.
+   */
   encryptData(
     plainData: Buffer,
     key: Buffer,
@@ -32,41 +64,123 @@ export interface InternalNamespace {
     authTag: Buffer;
   };
 
+  /**
+   * Decrypts AES-256-GCM encrypted data.
+   */
   decryptData(
-    cipherHex: string,
-    authTagHex: string,
+    cipherBuffer: Buffer,
+    authTagBuffer: Buffer,
     key: Buffer,
     iv: Buffer
   ): Buffer;
 }
 
+/**
+ * Main WilcoCrypt API.
+ */
 export interface WilcoCrypt {
   _: InternalNamespace;
 
+  /**
+   * Encrypts data using password-based AES-256-GCM.
+   *
+   * Output format:
+   * [HEADER (10 bytes)] + [VERSION (dynamic)] + [salt (16)] + [iv (12)] + [ciphertext] + [authTag (16)]
+   *
+   * @param plaindata Raw data to encrypt
+   * @param password Password used for key derivation
+   * @param gzip Whether to compress data before encryption (default: true)
+   * @returns Binary-encoded encrypted payload
+   */
   encryptData(
     plaindata: Buffer,
     password: string,
     gzip?: boolean
   ): Buffer;
 
+  /**
+   * Decrypts encrypted data using password-based AES-256-GCM.
+   *
+   * Validates internal header and version, then extracts:
+   * salt, iv, authTag and ciphertext from the binary payload.
+   *
+   * @param encryptedData Binary-encoded encrypted payload
+   * @param password Password used for decryption
+   * @param gzip Whether to decompress after decryption (default: true)
+   * @returns Decrypted raw data
+   *
+   * @throws WilcoCryptError on:
+   * - invalid header
+   * - version mismatch
+   * - wrong password
+   * - corrupted data
+   */
   decryptData(
     encryptedData: Buffer,
     password: string,
     gzip?: boolean
   ): Buffer;
 
+  /**
+   * Encrypts a file and writes `<filePath>.enc`.
+   */
   encryptFile(
     filePath: string,
     password: string,
     gzip?: boolean
   ): void;
 
-  decryptFile(
-    filePath: string,
+  /**
+   * Decrypts a `.enc` file.
+   *
+   * If `outputPath` is provided, the decrypted data is written to that file
+   * and `undefined` is returned. Otherwise the decrypted Buffer is returned.
+   */
+  decryptFile(filePath: string, password: string, outputPath: string, gzip?: boolean): undefined;
+  decryptFile(filePath: string, password: string, gzip?: boolean): Buffer;
+
+  /**
+   * Encrypts a file using streams and writes the result to `outputPath`.
+   * Memory-efficient alternative to `encryptFile` for large files.
+   *
+   * @param inputPath Path to the file to encrypt
+   * @param outputPath Path to write the encrypted output to
+   * @param password Password used for key derivation
+   * @param gzip Whether to compress data before encryption (default: true)
+   */
+  encryptFileStream(
+    inputPath: string,
+    outputPath: string,
     password: string,
     gzip?: boolean
-  ): Buffer;
+  ): Promise<void>;
+
+  /**
+   * Decrypts an encrypted file using streams.
+   * Memory-efficient alternative to `decryptFile` for large files.
+   * Cleans up the output file automatically if decryption or integrity check fails.
+   *
+   * @param inputPath Path to the encrypted file
+   * @param outputPath Path to write the decrypted output to
+   * @param password Password used for decryption
+   * @param gzip Whether to decompress after decryption (default: true)
+   *
+   * @throws WilcoCryptError on:
+   * - invalid header
+   * - version mismatch
+   * - decryption/integrity failure
+   */
+  decryptFileStream(
+    inputPath: string,
+    outputPath: string,
+    password: string,
+    gzip?: boolean
+  ): Promise<void>;
 }
 
+/**
+ * WilcoCrypt main instance.
+ */
 declare const wilcocrypt: WilcoCrypt;
+
 export default wilcocrypt;