wilcocrypt 2.1.1 → 2.2.1

package/README.md

@@ -1,21 +1,24 @@
 # WilcoCrypt
 
-**WilcoCrypt** is a small, secure, and predictable encryption library for Node.js.
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
 
-It is designed around strong defaults, minimal dependencies, and consistent behavior across environments — from servers to low-end devices like Raspberry Pi.
+> **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
+- scrypt key derivation with a random salt per encryption
 - Optional gzip compression before encryption
-- Compact binary format using MessagePack
-- Built-in versioning and compatibility checks
-- Clear and consistent error handling
-- Simple, dependency-light design
-- CLI for quick file encryption and decryption
+- Synchronous and asynchronous APIs
+- Streaming API for large files (`encryptFileStream` / `decryptFileStream`)
+- CLI with interactive password prompt
+- Comprehensive TypeScript definitions with full JSDoc support
+- Prettier code formatting
 
 ---
 
@@ -25,99 +28,92 @@ It is designed around strong defaults, minimal dependencies, and consistent beha
 npm install wilcocrypt
 ```
 
-### CLI (global)
-
-```bash
-npm install -g wilcocrypt
-```
+Requires Node.js 18 or later.
 
 ---
 
-## Usage (Node.js)
+## Quick Start
 
 ```js
-import wilcocrypt from 'wilcocrypt';
+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");
 
-// Decrypt a file
-const content = wilcocrypt.decryptFile('document.txt.enc', 'myStrongPassword');
+// Encrypt a file → writes file.txt.enc
+wilcocrypt.encryptFile("file.txt", "my-password");
 
-console.log(content);
-```
+// Decrypt to Buffer
+const buf = wilcocrypt.decryptFile("file.txt.enc", "my-password");
 
-### Working with Buffers
+// Decrypt directly to disk
+wilcocrypt.decryptFile("file.txt.enc", "my-password", "output.txt");
 
-```js
-import wilcocrypt from 'wilcocrypt';
-
-const data = Buffer.from('Hello world');
-
-// Encrypt
-const encrypted = wilcocrypt.encryptData(data, 'password');
-
-// Decrypt
-const decrypted = wilcocrypt.decryptData(encrypted, 'password');
-
-console.log(decrypted.toString());
+// 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");
 ```
 
 ---
 
-## CLI Usage
+## CLI
 
 ```bash
 # Encrypt
-wilcocrypt -e file.txt
-wilcocrypt --encrypt file.txt
+wilcocrypt -e secret.txt
+# → prompts for password, writes secret.txt.enc
+
+# Decrypt to stdout
+wilcocrypt -d secret.txt.enc
 
-# Decrypt
-wilcocrypt -d file.txt.enc
-wilcocrypt --decrypt file.txt.enc
+# Decrypt to a file
+wilcocrypt -d secret.txt.enc -o secret.txt
 ```
 
-The CLI will securely prompt for a password (input is masked).
+See `wilcocrypt --help` for all options.
 
 ---
 
-## Internal API
+## Binary Payload Format
 
-Advanced users can access internal helpers via:
-
-```js
-wilcocrypt._
+```
+[ HEADER (10) ] [ VERSION (dynamic) ] [ salt (16) ] [ iv (12) ] [ ciphertext ] [ authTag (16) ]
 ```
 
-These APIs are **not stable** and may change between versions.
-
----
+The auth tag is appended at the end for streaming compatibility. See [DOCS.md](./DOCS.md#binary-payload-format) for the full layout.
 
-## Format Overview
+> **Note:** The format changed in v2.2.0. Payloads from v2.1.x are not compatible.
 
-Encrypted output is stored as a MessagePack-encoded object containing:
+---
 
-- payload (ciphertext, hex)
-- authTag (hex)
-- salt (hex)
-- iv (hex)
-- version
+## 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.1.1**
-- Encrypted data must match the exact version
+Common codes: `WEAK_PASSWORD`, `INVALID_HEADER`, `VERSION_MISMATCH`, `DECRYPTION_FAILED`, `INVALID_FILE_EXTENSION`.
 
 ---
 
-## Security Notes
+## Documentation
+
+Full API reference, CLI docs, payload format, TypeScript usage, and security notes: **[DOCS.md](./DOCS.md)**
 
-- 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
+Changelog: **[CHANGELOG.md](./CHANGELOG.md)**
 
 ---
 

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.2.x   | :white_check_mark: |
+| 2.1.x   | :x:                |
+| 2.0.x   | :x:                |
+| 1.x     | :x:                |
+
+Only the latest minor version in the 2.x range receives 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
+
+- 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,6 +1,6 @@
 {
   "name": "wilcocrypt",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "A encrypting tool",
   "keywords": [
     "encrypting",
@@ -10,12 +10,16 @@
   "author": "computerwilco",
   "type": "module",
   "main": "src/wilcocrypt.js",
-  "bin": "src/cli.js",
+  "bin": {
+    "wilcocrypt": "src/cli.js"
+  },
   "types": "types/wilcocrypt.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "node src/cli.js",
+    "semistandard": "npx semistandard",
+    "lint": "npx semistandard --fix; npx prettier --write .",
     "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",
@@ -26,14 +30,16 @@
     "clean": "rm -rf dist && rm -rf sea/*.sea && rm -rf release/*"
   },
   "dependencies": {
-    "commander": "14.0.3",
-    "notepack.io": "3.0.1"
+    "commander": "15.0.0"
   },
   "devDependencies": {
-    "@rollup/plugin-commonjs": "29.0.2",
+    "@rollup/plugin-commonjs": "29.0.3",
     "@rollup/plugin-node-resolve": "16.0.3",
     "@rollup/plugin-replace": "6.0.3",
     "@rollup/plugin-terser": "1.0.0",
-    "rollup": "4.60.2"
+    "@types/node": "25.9.2",
+    "prettier": "3.8.3",
+    "rollup": "4.61.1",
+    "semistandard": "17.0.0"
   }
 }

package/src/cli.js

@@ -1,61 +1,62 @@
-import { Command } from 'commander';
-import wilcocrypt from './wilcocrypt.js';
+#!/usr/bin/env node
+import { Command } from "commander";
+import wilcocrypt from "./wilcocrypt.js";
 
 /* =========================
    Helpers
 ========================= */
 
-function promptPassword(promptText = 'Password: ') {
+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'
+        "Password prompt requires a TTY",
+        "NO_TTY",
       );
     }
-    
+
     stdout.write(promptText);
 
-    let password = '';
+    let password = "";
 
     stdin.setRawMode(true);
     stdin.resume();
-    stdin.setEncoding('utf8');
+    stdin.setEncoding("utf8");
 
     function onData(char) {
-      if (char === '\r' || char === '\n') {
-        stdout.write('\n');
+      if (char === "\r" || char === "\n") {
+        stdout.write("\n");
         stdin.setRawMode(false);
         stdin.pause();
-        stdin.removeListener('data', onData);
+        stdin.removeListener("data", onData);
         resolve(password);
         return;
       }
 
-      if (char === '\u0003') {
-        stdout.write('\n');
+      if (char === "\u0003") {
+        stdout.write("\n");
         stdin.setRawMode(false);
         stdin.pause();
-        stdin.removeListener('data', onData);
+        stdin.removeListener("data", onData);
         process.exit(1);
       }
 
-      if (char === '\u007f' || char === '\b') {
+      if (char === "\u007f" || char === "\b") {
         if (password.length > 0) {
           password = password.slice(0, -1);
-          stdout.write('\b \b');
+          stdout.write("\b \b");
         }
         return;
       }
 
       password += char;
-      stdout.write('*');
+      stdout.write("*");
     }
 
-    stdin.on('data', onData);
+    stdin.on("data", onData);
   });
 }
 
@@ -66,14 +67,22 @@ function promptPassword(promptText = 'Password: ') {
 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');
+  .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);
 
@@ -83,18 +92,24 @@ const options = program.opts();
    Validation
 ========================= */
 
-const actions = [
-  options.encrypt,
-  options.decrypt,
-  options.unpack
-].filter(Boolean);
+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, -d or --unpack)');
+  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);
 }
 
@@ -105,17 +120,22 @@ if (actions.length > 1) {
 (async () => {
   try {
     if (options.encrypt) {
-      const password = await promptPassword('Encryption password: ');
+      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;
+      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}`);