wilcocrypt 2.1.0 → 2.2.0

package/README.md

@@ -1,22 +1,23 @@
 # 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.
+[![js-semistandard-style](https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg)](https://github.com/standard/semistandard)
 
-The library focuses on strong defaults, portability, and predictable behavior across environments
-(including low-end devices such as Raspberry Pi and Android/Termux).
+> **The `master` branch may be unstable during active development.**
+> For production use, always install from [npm](https://www.npmjs.com/package/wilcocrypt) or use a tagged [GitHub Release](https://github.com/computer-wilco/wilcocrypt/releases).
+
+A simple, modern Node.js encryption library and CLI tool. AES-256-GCM, password-based key derivation via scrypt, optional gzip compression, and a streaming API for large files.
 
 ---
 
 ## Features
 
 - AES-256-GCM authenticated encryption
-- Password-based key derivation using scrypt
-- MessagePack + gzip for compact encrypted files
-- 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
+- scrypt key derivation with a random salt per encryption
+- Optional gzip compression before encryption
+- Streaming API for large files (`encryptFileStream` / `decryptFileStream`)
+- CLI with interactive password prompt
+- TypeScript types included
+- semistandard code style
 
 ---
 
@@ -26,86 +27,95 @@ The library focuses on strong defaults, portability, and predictable behavior ac
 npm install wilcocrypt
 ```
 
-### CLI Installation
-
-```bash
-npm install -g wilcocrypt
-```
+Requires Node.js 18 or later.
 
 ---
 
-## Usage (Node.js)
+## Quick Start
 
 ```js
 import wilcocrypt from 'wilcocrypt';
 
-// Encrypt a file
-wilcocrypt.encryptFile('document.txt', 'myStrongPassword');
+// Encrypt / decrypt a Buffer
+const encrypted = wilcocrypt.encryptData(Buffer.from('Hello!'), 'my-password');
+const decrypted = wilcocrypt.decryptData(encrypted, 'my-password');
+
+// Encrypt a file → writes file.txt.enc
+wilcocrypt.encryptFile('file.txt', 'my-password');
+
+// Decrypt to Buffer
+const buf = wilcocrypt.decryptFile('file.txt.enc', 'my-password');
 
-// Decrypt a file
-const content = wilcocrypt.decryptFile('document.txt.enc', 'myStrongPassword');
-console.log(content);
+// Decrypt directly to disk
+wilcocrypt.decryptFile('file.txt.enc', 'my-password', 'output.txt');
+
+// Stream API (memory-efficient for large files)
+await wilcocrypt.encryptFileStream('big.zip', 'big.zip.enc', 'my-password');
+await wilcocrypt.decryptFileStream('big.zip.enc', 'big.zip', 'my-password');
 ```
 
 ---
 
-## Internal helpers (optional)
+## CLI
 
-Advanced users can access internal helpers via `wilcocrypt._`.
-These APIs are considered internal and may change between versions.
+```bash
+# Encrypt
+wilcocrypt -e secret.txt
+# → prompts for password, writes secret.txt.enc
 
-```js
-const iv = Buffer.from('...');
-const key = Buffer.from('...');
-const encrypted = wilcocrypt._.encryptData(Buffer.from('Hello'), key, iv);
+# Decrypt to stdout
+wilcocrypt -d secret.txt.enc
+
+# Decrypt to a file
+wilcocrypt -d secret.txt.enc -o secret.txt
 ```
 
+See `wilcocrypt --help` for all options.
+
 ---
 
-## CLI Usage
+## Binary Payload Format
 
-Once installed globally:
+```
+[ HEADER (10) ] [ VERSION (dynamic) ] [ salt (16) ] [ iv (12) ] [ ciphertext ] [ authTag (16) ]
+```
 
-```bash
-# Encrypt a file
-wilcocrypt -e document.txt
-wilcocrypt --encrypt document.txt
+The auth tag is appended at the end for streaming compatibility. See [DOCS.md](./DOCS.md#binary-payload-format) for the full layout.
 
-# Decrypt a file
-wilcocrypt -d document.txt.enc
-wilcocrypt --decrypt document.txt.enc
+> **Note:** The format changed in v2.2.0. Payloads from v2.1.x are not compatible.
 
-# Internal: unpack raw encrypted envelope
-wilcocrypt --unpack document.txt.enc
-```
+---
 
-The CLI will securely prompt for a password (input is masked).
+## Error Handling
 
----
+All errors are instances of `WilcoCryptError` with a machine-readable `code` property.
 
-## Version
+```js
+import wilcocrypt from 'wilcocrypt';
+const { WilcoCryptError } = wilcocrypt._;
+
+try {
+  wilcocrypt.decryptData(payload, 'wrong');
+} catch (err) {
+  if (err instanceof WilcoCryptError) {
+    console.error(err.code);    // e.g. DECRYPTION_FAILED
+    console.error(err.message);
+  }
+}
+```
 
-- Current version: **2.0.0**
-- Version 1.x is deprecated and should not be used
+Common codes: `WEAK_PASSWORD`, `INVALID_HEADER`, `VERSION_MISMATCH`, `DECRYPTION_FAILED`, `INVALID_FILE_EXTENSION`.
 
 ---
 
-## License
+## Documentation
 
-WilcoCrypt is released under the **GPL-3.0-only** license.
+Full API reference, CLI docs, payload format, TypeScript usage, and security notes: **[DOCS.md](./DOCS.md)**
 
-You are free to:
-- Use the software for any purpose
-- Study how it works and modify it
-- Redistribute the software
-- Distribute modified versions
+Changelog: **[CHANGELOG.md](./CHANGELOG.md)**
 
-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.
+## License
 
-For full license text, see:
-https://www.gnu.org/licenses/gpl-3.0.html
+Licensed under **GPL-3.0-only**.

package/SECURITY.md

@@ -0,0 +1,48 @@
+# Security Policy
+
+## Supported Versions
+
+The following versions of WilcoCrypt are currently supported with security updates:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.1.x   | :white_check_mark: |
+| 2.0.x   | :x:                |
+| 1.x     | :x:                |
+
+Only the latest minor version in the 2.x range receives security updates. All the versions below that are not supported.
+
+---
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in WilcoCrypt, please report it responsibly.
+
+### How to report
+
+- Open a **private security advisory** via the GitHub repository
+
+Please include:
+
+* A clear description of the issue
+* Steps to reproduce (if possible)
+* Impact assessment (what can go wrong)
+
+### What to expect
+
+* You will receive a response within **48 hours**
+* I will investigate and confirm the issue
+* If accepted, a fix will be developed as soon as possible
+* A patched version will be released and documented
+
+### Responsible disclosure
+
+Please do **not** publicly disclose the vulnerability until a fix has been released.
+
+---
+
+## Notes
+
+* WilcoCrypt is designed with strong cryptographic defaults, but misuse (e.g. weak passwords) can still lead to insecure outcomes
+* Always use strong, unique passwords
+* Security is a shared responsibility between the library and its users

package/package.json

@@ -1,19 +1,23 @@
 {
   "name": "wilcocrypt",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "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",
+    "test": "node src/cli.js",
+    "lint": "npx semistandard",
+    "lint:fix": "npx semistandard --fix",
     "update": "npx -y Jelmerro/nus",
-    "rollup": "rollup -c && node src/scripts/fix-cli-min-import.js && node src/scripts/chmod.js",
+    "rollup": "node src/scripts/shebang-fix.js pre && rollup -c && node src/scripts/shebang-fix.js post && node src/scripts/fix-cli-min-import.js && node src/scripts/chmod.js",
     "sea:blob": "node src/scripts/sea-blob.js",
     "sea:linux-x64": "cp node-binaries/linux-x64/node release/wilcocrypt-linux-x64 && npx postject release/wilcocrypt-linux-x64 NODE_SEA_BLOB sea/wilcocrypt.sea --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 && chmod +x release/wilcocrypt-linux-x64",
     "sea:linux-arm64": "cp node-binaries/linux-arm64/node release/wilcocrypt-linux-arm64 && npx postject release/wilcocrypt-linux-arm64 NODE_SEA_BLOB sea/wilcocrypt.sea --sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2 && chmod +x release/wilcocrypt-linux-arm64",
@@ -23,13 +27,16 @@
     "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"
+  },
   "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"
+    "@types/node": "25.6.0",
+    "rollup": "4.60.2",
+    "semistandard": "17.0.0"
   }
 }

package/src/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+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')
+  .option('-o, --output <file>', 'Write output to file instead of stdout (decrypt only)')
+  .option('--stdout', 'Write decrypted output to stdout (default behavior, explicit flag)')
+
+  .helpOption('-h, --help', 'Display help');
+
+program.parse(process.argv);
+
+const options = program.opts();
+
+/* =========================
+   Validation
+========================= */
+
+const actions = [
+  options.encrypt,
+  options.decrypt
+].filter(Boolean);
+
+if (actions.length === 0) {
+  program.help();
+}
+
+if (actions.length > 1) {
+  console.error('error: please specify only one action (-e or -d)');
+  process.exit(1);
+}
+
+if (options.output && options.stdout) {
+  console.error('error: --output and --stdout are mutually exclusive');
+  process.exit(1);
+}
+
+if (options.output && options.encrypt) {
+  console.error('error: --output is only supported for decryption');
+  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: ');
+
+      if (options.output) {
+        wilcocrypt.decryptFile(options.decrypt, password, options.output);
+        console.log(`Decrypted: ${options.output}`);
+      } else {
+        const result = wilcocrypt.decryptFile(options.decrypt, password);
+        process.stdout.write(result);
+      }
+    }
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(1);
+  }
+})();