wilcocrypt 2.1.1 → 2.2.0

package/README.md

@@ -1,21 +1,23 @@
 # WilcoCrypt
 
-**WilcoCrypt** is a small, secure, and predictable encryption library for Node.js.
+[![js-semistandard-style](https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg)](https://github.com/standard/semistandard)
 
-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
+- Streaming API for large files (`encryptFileStream` / `decryptFileStream`)
+- CLI with interactive password prompt
+- TypeScript types included
+- semistandard code style
 
 ---
 
@@ -25,99 +27,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';
 
-// Encrypt a file
-wilcocrypt.encryptFile('document.txt', 'myStrongPassword');
-
-// Decrypt a file
-const content = wilcocrypt.decryptFile('document.txt.enc', 'myStrongPassword');
-
-console.log(content);
-```
-
-### Working with Buffers
-
-```js
-import wilcocrypt from 'wilcocrypt';
+// Encrypt / decrypt a Buffer
+const encrypted = wilcocrypt.encryptData(Buffer.from('Hello!'), 'my-password');
+const decrypted = wilcocrypt.decryptData(encrypted, 'my-password');
 
-const data = Buffer.from('Hello world');
+// Encrypt a file → writes file.txt.enc
+wilcocrypt.encryptFile('file.txt', 'my-password');
 
-// Encrypt
-const encrypted = wilcocrypt.encryptData(data, 'password');
+// Decrypt to Buffer
+const buf = wilcocrypt.decryptFile('file.txt.enc', 'my-password');
 
-// Decrypt
-const decrypted = wilcocrypt.decryptData(encrypted, 'password');
+// Decrypt directly to disk
+wilcocrypt.decryptFile('file.txt.enc', 'my-password', 'output.txt');
 
-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.
 
----
+> **Note:** The format changed in v2.2.0. Payloads from v2.1.x are not compatible.
 
-## Format Overview
+---
 
-Encrypted output is stored as a MessagePack-encoded object containing:
+## Error Handling
 
-- payload (ciphertext, hex)
-- authTag (hex)
-- salt (hex)
-- iv (hex)
-- version
+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.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,6 +1,6 @@
 {
   "name": "wilcocrypt",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "A encrypting tool",
   "keywords": [
     "encrypting",
@@ -13,9 +13,11 @@
   "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",
@@ -26,14 +28,15 @@
     "clean": "rm -rf dist && rm -rf sea/*.sea && rm -rf release/*"
   },
   "dependencies": {
-    "commander": "14.0.3",
-    "notepack.io": "3.0.1"
+    "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",
-    "rollup": "4.60.2"
+    "@types/node": "25.6.0",
+    "rollup": "4.60.2",
+    "semistandard": "17.0.0"
   }
 }

package/src/cli.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { Command } from 'commander';
 import wilcocrypt from './wilcocrypt.js';
 
@@ -5,7 +6,7 @@ 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;
@@ -16,7 +17,7 @@ function promptPassword(promptText = 'Password: ') {
         'NO_TTY'
       );
     }
-    
+
     stdout.write(promptText);
 
     let password = '';
@@ -25,7 +26,7 @@ function promptPassword(promptText = 'Password: ') {
     stdin.resume();
     stdin.setEncoding('utf8');
 
-    function onData(char) {
+    function onData (char) {
       if (char === '\r' || char === '\n') {
         stdout.write('\n');
         stdin.setRawMode(false);
@@ -72,6 +73,8 @@ program
 
   .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');
 
@@ -85,8 +88,7 @@ const options = program.opts();
 
 const actions = [
   options.encrypt,
-  options.decrypt,
-  options.unpack
+  options.decrypt
 ].filter(Boolean);
 
 if (actions.length === 0) {
@@ -94,7 +96,17 @@ if (actions.length === 0) {
 }
 
 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);
 }
 
@@ -113,9 +125,14 @@ if (actions.length > 1) {
 
     if (options.decrypt) {
       const password = await promptPassword('Decryption password: ');
-      const result = wilcocrypt.decryptFile(options.decrypt, password);
-      process.stdout.write(result);
-      return;
+
+      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}`);