wilcocrypt 2.1.0 → 2.1.1

package/README.md

@@ -1,10 +1,8 @@
 # WilcoCrypt
 
-**WilcoCrypt** is a simple and secure file encryption tool for Node.js.  
-It offers both a clean programmatic API and a practical command-line interface (CLI) for everyday use.
+**WilcoCrypt** is a small, secure, and predictable encryption library for Node.js.
 
-The library focuses on strong defaults, portability, and predictable behavior across environments
-(including low-end devices such as Raspberry Pi and Android/Termux).
+It is designed around strong defaults, minimal dependencies, and consistent behavior across environments — from servers to low-end devices like Raspberry Pi.
 
 ---
 
@@ -12,11 +10,12 @@ The library focuses on strong defaults, portability, and predictable behavior ac
 
 - AES-256-GCM authenticated encryption
 - Password-based key derivation using scrypt
-- MessagePack + gzip for compact encrypted files
+- Optional gzip compression before encryption
+- Compact binary format using MessagePack
 - Built-in versioning and compatibility checks
 - Clear and consistent error handling
-- Clean separation between public API and internal helpers
-- Command-line interface (CLI) for quick file encryption and decryption
+- Simple, dependency-light design
+- CLI for quick file encryption and decryption
 
 ---
 
@@ -26,7 +25,7 @@ The library focuses on strong defaults, portability, and predictable behavior ac
 npm install wilcocrypt
 ```
 
-### CLI Installation
+### CLI (global)
 
 ```bash
 npm install -g wilcocrypt
@@ -44,68 +43,84 @@ wilcocrypt.encryptFile('document.txt', 'myStrongPassword');
 
 // Decrypt a file
 const content = wilcocrypt.decryptFile('document.txt.enc', 'myStrongPassword');
+
 console.log(content);
 ```
 
----
+### Working with Buffers
 
-## Internal helpers (optional)
+```js
+import wilcocrypt from 'wilcocrypt';
 
-Advanced users can access internal helpers via `wilcocrypt._`.
-These APIs are considered internal and may change between versions.
+const data = Buffer.from('Hello world');
 
-```js
-const iv = Buffer.from('...');
-const key = Buffer.from('...');
-const encrypted = wilcocrypt._.encryptData(Buffer.from('Hello'), key, iv);
+// Encrypt
+const encrypted = wilcocrypt.encryptData(data, 'password');
+
+// Decrypt
+const decrypted = wilcocrypt.decryptData(encrypted, 'password');
+
+console.log(decrypted.toString());
 ```
 
 ---
 
 ## CLI Usage
 
-Once installed globally:
-
 ```bash
-# Encrypt a file
-wilcocrypt -e document.txt
-wilcocrypt --encrypt document.txt
-
-# Decrypt a file
-wilcocrypt -d document.txt.enc
-wilcocrypt --decrypt document.txt.enc
+# Encrypt
+wilcocrypt -e file.txt
+wilcocrypt --encrypt file.txt
 
-# Internal: unpack raw encrypted envelope
-wilcocrypt --unpack document.txt.enc
+# Decrypt
+wilcocrypt -d file.txt.enc
+wilcocrypt --decrypt file.txt.enc
 ```
 
 The CLI will securely prompt for a password (input is masked).
 
 ---
 
-## Version
+## Internal API
+
+Advanced users can access internal helpers via:
+
+```js
+wilcocrypt._
+```
 
-- Current version: **2.0.0**
-- Version 1.x is deprecated and should not be used
+These APIs are **not stable** and may change between versions.
 
 ---
 
-## License
+## Format Overview
 
-WilcoCrypt is released under the **GPL-3.0-only** license.
+Encrypted output is stored as a MessagePack-encoded object containing:
 
-You are free to:
-- Use the software for any purpose
-- Study how it works and modify it
-- Redistribute the software
-- Distribute modified versions
+- payload (ciphertext, hex)
+- authTag (hex)
+- salt (hex)
+- iv (hex)
+- version
 
-Under the condition that:
-- Any distributed derivative work is also licensed under GPL-3.0-only
-- The source code remains available to users
+---
 
-This software is provided **without any warranty**.
-Use it at your own risk.
+## Version
+
+- Current version: **2.1.1**
+- Encrypted data must match the exact version
+
+---
+
+## Security Notes
+
+- Always use strong, unique passwords
+- Losing the password means permanent data loss
+- Do not modify encrypted files manually
+- Compression can be disabled if not needed
+
+---
+
+## License
 
-For full license text, see:
-https://www.gnu.org/licenses/gpl-3.0.html
+Licensed under **GPL-3.0-only**.

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "wilcocrypt",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "A encrypting tool",
   "keywords": [
-    "encrypting"
+    "encrypting",
+    "crypto"
   ],
   "license": "GPL-3.0-only",
-  "author": "Wilco Joosen",
+  "author": "computerwilco",
   "type": "module",
-  "main": "dist/wilcocrypt.min.js",
-  "bin": "dist/cli.min.js",
+  "main": "src/wilcocrypt.js",
+  "bin": "src/cli.js",
+  "types": "types/wilcocrypt.d.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "update": "npx -y Jelmerro/nus",
@@ -23,13 +25,15 @@
     "build": "npm run rollup && npm run sea:blob && npm run sea:linux-x64 && npm run sea:linux-arm64 && npm run sea:windows-x64 && npm run sea:macos-x64 && npm run sea:macos-arm64",
     "clean": "rm -rf dist && rm -rf sea/*.sea && rm -rf release/*"
   },
+  "dependencies": {
+    "commander": "14.0.3",
+    "notepack.io": "3.0.1"
+  },
   "devDependencies": {
     "@rollup/plugin-commonjs": "29.0.2",
     "@rollup/plugin-node-resolve": "16.0.3",
     "@rollup/plugin-replace": "6.0.3",
     "@rollup/plugin-terser": "1.0.0",
-    "commander": "14.0.3",
-    "notepack.io": "3.0.1",
     "rollup": "4.60.2"
   }
 }

package/src/cli.js

@@ -0,0 +1,124 @@
+import { Command } from 'commander';
+import wilcocrypt from './wilcocrypt.js';
+
+/* =========================
+   Helpers
+========================= */
+
+function promptPassword(promptText = 'Password: ') {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+
+    if (!stdin.isTTY) {
+      throw new wilcocrypt._.WilcoCryptError(
+        'Password prompt requires a TTY',
+        'NO_TTY'
+      );
+    }
+    
+    stdout.write(promptText);
+
+    let password = '';
+
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    function onData(char) {
+      if (char === '\r' || char === '\n') {
+        stdout.write('\n');
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdin.removeListener('data', onData);
+        resolve(password);
+        return;
+      }
+
+      if (char === '\u0003') {
+        stdout.write('\n');
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdin.removeListener('data', onData);
+        process.exit(1);
+      }
+
+      if (char === '\u007f' || char === '\b') {
+        if (password.length > 0) {
+          password = password.slice(0, -1);
+          stdout.write('\b \b');
+        }
+        return;
+      }
+
+      password += char;
+      stdout.write('*');
+    }
+
+    stdin.on('data', onData);
+  });
+}
+
+/* =========================
+   CLI setup
+========================= */
+
+const program = new Command();
+
+program
+  .name('wilcocrypt')
+  .description('File encryption tool')
+  .version(wilcocrypt._.VERSION, '--version', 'Show version')
+
+  .option('-e, --encrypt <file>', 'Encrypt file')
+  .option('-d, --decrypt <file>', 'Decrypt file')
+
+  .helpOption('-h, --help', 'Display help');
+
+program.parse(process.argv);
+
+const options = program.opts();
+
+/* =========================
+   Validation
+========================= */
+
+const actions = [
+  options.encrypt,
+  options.decrypt,
+  options.unpack
+].filter(Boolean);
+
+if (actions.length === 0) {
+  program.help();
+}
+
+if (actions.length > 1) {
+  console.error('error: please specify only one action (-e, -d or --unpack)');
+  process.exit(1);
+}
+
+/* =========================
+   Actions
+========================= */
+
+(async () => {
+  try {
+    if (options.encrypt) {
+      const password = await promptPassword('Encryption password: ');
+      wilcocrypt.encryptFile(options.encrypt, password);
+      console.log(`Encrypted: ${options.encrypt}.enc`);
+      return;
+    }
+
+    if (options.decrypt) {
+      const password = await promptPassword('Decryption password: ');
+      const result = wilcocrypt.decryptFile(options.decrypt, password);
+      process.stdout.write(result);
+      return;
+    }
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(1);
+  }
+})();

package/src/wilcocrypt.js

@@ -0,0 +1,302 @@
+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';
+
+/**
+ * Main WilcoCrypt namespace.
+ */
+const wilcocrypt = {};
+
+/**
+ * Internal WilcoCrypt utilities and constants.
+ */
+wilcocrypt._ = {};
+
+/* =========================
+   Custom Error
+========================= */
+
+/**
+ * Custom error class for all WilcoCrypt-specific errors.
+ */
+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') {
+    super(message);
+    this.name = 'WilcoCryptError';
+    this.code = code;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, WilcoCryptError);
+    }
+  }
+}
+
+wilcocrypt._.WilcoCryptError = WilcoCryptError;
+
+/* =========================
+   Internal constants
+========================= */
+
+/**
+ * Internal WilcoCrypt version.
+ * Must match exactly during decryption.
+ * @type {string}
+ */
+wilcocrypt._.VERSION = '2.1.1';
+
+/**
+ * Minimum allowed password length.
+ * @type {number}
+ */
+wilcocrypt._.MIN_PASSWORD_LENGTH = 6;
+
+/* =========================
+   Internal helpers
+========================= */
+
+/**
+ * Validates AES-256-GCM key and IV.
+ *
+ * @param {Buffer} key
+ * @param {Buffer} iv
+ * @throws {WilcoCryptError}
+ */
+wilcocrypt._.assertKeyAndIv = function (key, iv) {
+  if (!Buffer.isBuffer(key) || key.length !== 32) {
+    throw new WilcoCryptError(
+      'Invalid encryption key (expected 32-byte Buffer)',
+      'INVALID_KEY'
+    );
+  }
+
+  if (!Buffer.isBuffer(iv) || iv.length !== 12) {
+    throw new WilcoCryptError(
+      'Invalid IV (expected 12-byte Buffer for GCM)',
+      'INVALID_IV'
+    );
+  }
+};
+
+/**
+ * Validates password strength.
+ *
+ * @param {string} password
+ * @throws {WilcoCryptError}
+ */
+wilcocrypt._.assertPassword = function (password) {
+  if (typeof password !== 'string' || password.length < wilcocrypt._.MIN_PASSWORD_LENGTH) {
+    throw new WilcoCryptError(
+      `Password must be at least ${wilcocrypt._.MIN_PASSWORD_LENGTH} characters`,
+      'WEAK_PASSWORD'
+    );
+  }
+};
+
+/**
+ * Constant-time buffer comparison.
+ * Reserved for future extensions.
+ *
+ * @param {Buffer} a
+ * @param {Buffer} b
+ * @returns {boolean}
+ */
+wilcocrypt._.constantTimeEqual = function (a, b) {
+  if (a.length !== b.length) return false;
+
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a[i] ^ b[i];
+  }
+  return result === 0;
+};
+
+/* =========================
+   Crypto layer (internal)
+========================= */
+
+/**
+ * Encrypts raw data using AES-256-GCM.
+ *
+ * @param {Buffer} plainData
+ * @param {Buffer} key
+ * @param {Buffer} iv
+ * @returns {{ciphertext: Buffer, authTag: Buffer}}
+ */
+wilcocrypt._.encryptData = function (plainData, key, iv) {
+  wilcocrypt._.assertKeyAndIv(key, iv);
+
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(plainData),
+    cipher.final()
+  ]);
+
+  return {
+    ciphertext: encrypted,
+    authTag: cipher.getAuthTag()
+  };
+};
+
+/**
+ * Decrypts AES-256-GCM encrypted data.
+ *
+ * @param {string} cipherHex
+ * @param {string} authTagHex
+ * @param {Buffer} key
+ * @param {Buffer} iv
+ * @returns {Buffer}
+ */
+wilcocrypt._.decryptData = function (cipherHex, authTagHex, key, iv) {
+  wilcocrypt._.assertKeyAndIv(key, iv);
+
+  try {
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(Buffer.from(authTagHex, 'hex'));
+
+    return Buffer.concat([
+      decipher.update(Buffer.from(cipherHex, 'hex')),
+      decipher.final()
+    ]);
+  } catch {
+    throw new WilcoCryptError(
+      'Decryption failed (invalid password, corrupted data, or tampered file)',
+      'DECRYPTION_FAILED'
+    );
+  }
+};
+
+/* =========================
+   Public API
+========================= */
+
+/**
+ * Encrypts data using password-based AES-256-GCM.
+ *
+ * @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
+ * @throws {WilcoCryptError} If password is invalid
+ */
+wilcocrypt.encryptData = function (plaindata, password, gzip = true) {
+    wilcocrypt._.assertPassword(password);
+
+    let gzipData;
+    if (gzip) {
+        gzipData = gzipSync(plaindata);
+    } else {
+        gzipData = plaindata;
+    }
+
+    const iv = randomBytes(12);
+    const salt = randomBytes(16);
+
+    const key = scryptSync(password, salt, 32);
+
+    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);
+};
+
+/**
+ * Decrypts encrypted data using password-based AES-256-GCM.
+ *
+ * @param {Buffer} encryptedData - MessagePack-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
+ */
+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'
+        );
+    }
+
+    if (envelope.version !== wilcocrypt._.VERSION) {
+        throw new WilcoCryptError(
+            `Version mismatch (expected ${wilcocrypt._.VERSION}, got ${envelope.version})`,
+            'VERSION_MISMATCH'
+        );
+    }
+
+    const key = scryptSync(password, Buffer.from(envelope.salt, 'hex'), 32);
+
+    const decrypted = wilcocrypt._.decryptData(
+        envelope.payload,
+        envelope.authTag,
+        key,
+        Buffer.from(envelope.iv, 'hex')
+    );
+
+    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'
+        );
+    }
+};
+
+/**
+ * Encrypts a file and writes the result to `<filePath>.enc`.
+ *
+ * @param {string} filePath - Path to the file to encrypt
+ * @param {string} password - Password used for encryption
+ * @param {boolean} [gzip=true] - Whether to compress before encryption
+ * @returns {void}
+ * @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);
+};
+
+/**
+ * Decrypts an encrypted `.enc` file.
+ *
+ * @param {string} filePath - Path to the `.enc` file
+ * @param {string} password - Password used for decryption
+ * @param {boolean} [gzip=true] - Whether to decompress after decryption
+ * @returns {Buffer} Decrypted file contents
+ * @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'
+        );
+    }
+
+    const encryptedData = readFileSync(filePath);
+    return wilcocrypt.decryptData(encryptedData, password, gzip);
+};
+
+export default wilcocrypt;

package/types/wilcocrypt.d.ts

@@ -0,0 +1,72 @@
+/// <reference types="node" />
+
+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;
+}
+
+export interface InternalNamespace {
+  VERSION: string;
+  MIN_PASSWORD_LENGTH: number;
+
+  WilcoCryptError: typeof WilcoCryptError;
+
+  assertKeyAndIv(key: Buffer, iv: Buffer): void;
+  assertPassword(password: string): void;
+  constantTimeEqual(a: Buffer, b: Buffer): boolean;
+
+  encryptData(
+    plainData: Buffer,
+    key: Buffer,
+    iv: Buffer
+  ): {
+    ciphertext: Buffer;
+    authTag: Buffer;
+  };
+
+  decryptData(
+    cipherHex: string,
+    authTagHex: string,
+    key: Buffer,
+    iv: Buffer
+  ): Buffer;
+}
+
+export interface WilcoCrypt {
+  _: InternalNamespace;
+
+  encryptData(
+    plaindata: Buffer,
+    password: string,
+    gzip?: boolean
+  ): Buffer;
+
+  decryptData(
+    encryptedData: Buffer,
+    password: string,
+    gzip?: boolean
+  ): Buffer;
+
+  encryptFile(
+    filePath: string,
+    password: string,
+    gzip?: boolean
+  ): void;
+
+  decryptFile(
+    filePath: string,
+    password: string,
+    gzip?: boolean
+  ): Buffer;
+}
+
+declare const wilcocrypt: WilcoCrypt;
+export default wilcocrypt;