wilcocrypt 2.1.0 → 2.2.0

package/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,78 @@
+name: Bug report
+about: Report a bug or unexpected behavior in WilcoCrypt
+title: "[BUG] "
+labels: ["bug"]
+
+body:
+  - type: markdown
+    attributes:
+      value: "## Bug report"
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Describe what went wrong
+      placeholder: Clearly explain the issue
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: How can this issue be reproduced?
+      value: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened?
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: WilcoCrypt version
+      placeholder: e.g. 2.1.1
+    validations:
+      required: true
+
+  - type: input
+    id: node
+    attributes:
+      label: Node.js version
+      placeholder: e.g. 22.x
+
+  - type: dropdown
+    id: environment
+    attributes:
+      label: Environment
+      options:
+        - Linux
+        - Windows
+        - macOS
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Logs, errors, or anything else

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+blank_issues_enabled: false
+
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/computer-wilco/wilcocrypt/security/advisories
+    about: Report security vulnerabilities privately via GitHub Security Advisories

package/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,38 @@
+name: Feature request
+about: Suggest an idea or improvement for WilcoCrypt
+title: "[FEATURE] "
+labels: ["enhancement"]
+
+body:
+  - type: markdown
+    attributes:
+      value: "## Feature request"
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this solve?
+      placeholder: Describe the issue you're facing
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like to see?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any alternative solutions you've thought about?
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Extra details, use cases, or examples

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to WilcoCrypt are documented here.
+
+---
+
+## [2.2.0] - 2026-05-01
+
+### Added
+
+- **Streaming API** — `encryptFileStream(inputPath, outputPath, password, gzip?)` and `decryptFileStream(inputPath, outputPath, password, gzip?)` for memory-efficient encryption and decryption of large files using Node.js streams.
+- **`decryptFile` output path** — `decryptFile` now accepts an optional `outputPath` argument. When provided, decrypted data is written directly to that file instead of being returned as a Buffer. Fully backward compatible.
+- Internal `HEADER` constant (`[23, 9, 12, 3, 15, 3, 18, 25, 16, 20]`) for payload identification.
+- **CLI `-o` / `--output` flag** — Decrypted output can now be written to a file via `-o <file>` instead of always piping to stdout.
+- **CLI `--stdout` flag** — Explicit flag to write decrypted output to stdout (this remains the default when `-o` is omitted).
+- **Version check on decryption** — The version string is now embedded in the encrypted payload and validated during decryption. Payloads from a different version are rejected with a `VERSION_MISMATCH` error.
+- **GitHub issue templates** (bug report, feature request) and `issue_config.yml`.
+- **`dependabot.yml`** for automated dependency updates.
+- **`SECURITY.md`** with responsible disclosure policy.
+- **`DOCS.md`** — full API reference, CLI docs, payload format, TypeScript usage, and security notes.
+
+### Changed
+
+- **Binary payload format** — The encrypted payload format has been updated. The version string is now included between the header and salt, and the auth tag has moved to the **end** of the payload (after the ciphertext) to support streaming. The new layout is:
+  `[HEADER (10)] + [VERSION (dynamic)] + [salt (16)] + [iv (12)] + [ciphertext] + [authTag (16)]`
+  > Payloads encrypted with v2.1.1 are not compatible with v2.2.0 and vice versa.
+- **Removed `notepack.io`** — The MessagePack dependency has been dropped entirely. The custom binary format replaces the previous envelope-based approach.
+- **VERSION** bumped from `2.1.1` to `2.2.0`.
+- **Linting** — Codebase now enforces [semistandard](https://github.com/standard/semistandard) style (Standard JS + semicolons).
+- **TypeScript types** updated with overloads for the new `decryptFile` signature and the two new stream methods.
+- **README** updated with stability warning, new features, and links to `DOCS.md` and `CHANGELOG.md`.
+
+### Internal
+
+- Stream decryption performs early header and version validation before opening the output stream, and automatically cleans up the output file on failure.
+- `_.decryptData` internal helper now accepts raw `Buffer` arguments (previously hex strings).
+
+### Fixed Bugs
+
+- Fixed the bug where the CLI tool would not work when running with npx or global
+
+---
+
+## [2.1.1] - 2026-04-26
+
+First official GitHub release of WilcoCrypt.
+
+### Added
+
+- Full TypeScript support (`wilcocrypt.d.ts`).
+- Pre-built binaries for Linux x64/arm64, macOS x64/arm64, and Windows x64.
+- `WilcoCryptError` custom error class with machine-readable `code` property.
+- Internal helpers: `assertKeyAndIv`, `assertPassword`, `constantTimeEqual`.
+
+### Changed
+
+- Removed Rollup bundle from the npm package (Rollup is still used for building binaries).
+- README improvements and consistency fixes.
+
+### Notes
+
+- The CLI `wilcocrypt` command does not work when installed globally via npm in this release. Use the provided binaries as a workaround. This is fixed in v2.2.0.

package/DOCS.md

@@ -0,0 +1,335 @@
+# WilcoCrypt Documentation
+
+Complete reference for the WilcoCrypt API, CLI, and binary format.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [encryptData](#encryptdata)
+  - [decryptData](#decryptdata)
+  - [encryptFile](#encryptfile)
+  - [decryptFile](#decryptfile)
+  - [encryptFileStream](#encryptfilestream)
+  - [decryptFileStream](#decryptfilestream)
+  - [Internal Namespace (`_`)](#internal-namespace-_)
+- [CLI Reference](#cli-reference)
+- [Binary Payload Format](#binary-payload-format)
+- [Error Handling](#error-handling)
+- [TypeScript](#typescript)
+- [Security Notes](#security-notes)
+
+---
+
+## Installation
+
+```bash
+npm install wilcocrypt
+```
+
+Requires Node.js 18 or later (uses `stream/promises` and `fs/promises`).
+
+---
+
+## Quick Start
+
+```js
+import wilcocrypt from 'wilcocrypt';
+
+// Encrypt a Buffer
+const data = Buffer.from('Hello, world!');
+const encrypted = wilcocrypt.encryptData(data, 'my-password');
+
+// Decrypt it back
+const decrypted = wilcocrypt.decryptData(encrypted, 'my-password');
+console.log(decrypted.toString()); // Hello, world!
+
+// Encrypt a file (writes file.txt.enc)
+wilcocrypt.encryptFile('file.txt', 'my-password');
+
+// Decrypt a file (returns Buffer)
+const contents = wilcocrypt.decryptFile('file.txt.enc', 'my-password');
+
+// Decrypt a file directly to disk
+wilcocrypt.decryptFile('file.txt.enc', 'my-password', 'output.txt');
+```
+
+---
+
+## API Reference
+
+### `encryptData(plaindata, password, gzip?)`
+
+Encrypts a Buffer using password-based AES-256-GCM. The password is never stored; a random salt is generated for every encryption call.
+
+| Parameter  | Type      | Default | Description                          |
+|------------|-----------|---------|--------------------------------------|
+| `plaindata`| `Buffer`  | —       | Raw data to encrypt                  |
+| `password` | `string`  | —       | Password for key derivation (min. 6 chars) |
+| `gzip`     | `boolean` | `true`  | Compress data before encryption      |
+
+**Returns:** `Buffer` — the encrypted payload in the [binary format](#binary-payload-format).
+
+**Throws:** `WilcoCryptError` with code `WEAK_PASSWORD` if the password is too short.
+
+```js
+const encrypted = wilcocrypt.encryptData(Buffer.from('secret'), 'passw0rd');
+```
+
+---
+
+### `decryptData(encryptedBuffer, password, gzip?)`
+
+Decrypts a payload produced by `encryptData`. Validates the header and version before attempting decryption.
+
+| Parameter         | Type      | Default | Description                         |
+|-------------------|-----------|---------|-------------------------------------|
+| `encryptedBuffer` | `Buffer`  | —       | Payload from `encryptData`          |
+| `password`        | `string`  | —       | Password used during encryption     |
+| `gzip`            | `boolean` | `true`  | Decompress after decryption         |
+
+**Returns:** `Buffer` — the original plaintext data.
+
+**Throws:**
+
+| Code                | Reason                                    |
+|---------------------|-------------------------------------------|
+| `WEAK_PASSWORD`     | Password shorter than 6 characters       |
+| `INVALID_HEADER`    | Not a valid WilcoCrypt payload           |
+| `VERSION_MISMATCH`  | Payload was encrypted with a different version |
+| `DECRYPTION_FAILED` | Wrong password, tampered or corrupt data |
+
+```js
+const plain = wilcocrypt.decryptData(encrypted, 'passw0rd');
+```
+
+---
+
+### `encryptFile(filePath, password, gzip?)`
+
+Reads a file, encrypts it, and writes the result to `<filePath>.enc`. Uses `encryptData` internally, so the entire file is loaded into memory. For large files, use [`encryptFileStream`](#encryptfilestream) instead.
+
+| Parameter  | Type      | Default | Description                     |
+|------------|-----------|---------|---------------------------------|
+| `filePath` | `string`  | —       | Path to the source file         |
+| `password` | `string`  | —       | Password for key derivation     |
+| `gzip`     | `boolean` | `true`  | Compress before encryption      |
+
+**Returns:** `void`
+
+```js
+wilcocrypt.encryptFile('document.pdf', 'passw0rd');
+// Creates document.pdf.enc
+```
+
+---
+
+### `decryptFile(filePath, password, outputPath?, gzip?)`
+
+Decrypts a `.enc` file. If `outputPath` is provided, the result is written to disk and `undefined` is returned. Otherwise the decrypted `Buffer` is returned.
+
+| Parameter    | Type      | Default     | Description                                           |
+|--------------|-----------|-------------|-------------------------------------------------------|
+| `filePath`   | `string`  | —           | Path to the `.enc` file                               |
+| `password`   | `string`  | —           | Password used during encryption                       |
+| `outputPath` | `string`  | `undefined` | Optional path to write decrypted output to            |
+| `gzip`       | `boolean` | `true`      | Decompress after decryption                           |
+
+> The legacy 3-argument form `decryptFile(filePath, password, gzip)` is still fully supported, but will be deprecated in the next release.
+
+**Returns:** `Buffer` when no `outputPath` is given, `undefined` otherwise.
+
+**Throws:** `WilcoCryptError` with code `INVALID_FILE_EXTENSION` if `filePath` does not end in `.enc`.
+
+```js
+// Return as Buffer
+const buf = wilcocrypt.decryptFile('document.pdf.enc', 'passw0rd');
+
+// Write directly to disk
+wilcocrypt.decryptFile('document.pdf.enc', 'passw0rd', 'document.pdf');
+```
+
+---
+
+### `encryptFileStream(inputPath, outputPath, password, gzip?)`
+
+Streaming equivalent of `encryptFile`. Reads from `inputPath` and writes to `outputPath` chunk by chunk — suitable for large files where loading everything into memory is impractical.
+
+| Parameter    | Type      | Default | Description                          |
+|--------------|-----------|---------|--------------------------------------|
+| `inputPath`  | `string`  | —       | Path to the source file              |
+| `outputPath` | `string`  | —       | Path for the encrypted output        |
+| `password`   | `string`  | —       | Password for key derivation          |
+| `gzip`       | `boolean` | `true`  | Compress before encryption           |
+
+**Returns:** `Promise<void>`
+
+```js
+await wilcocrypt.encryptFileStream('bigfile.zip', 'bigfile.zip.enc', 'passw0rd');
+```
+
+---
+
+### `decryptFileStream(inputPath, outputPath, password, gzip?)`
+
+Streaming equivalent of `decryptFile`. Header and version are validated before the stream starts. If decryption fails at any point, the partially written output file is deleted automatically.
+
+| Parameter    | Type      | Default | Description                           |
+|--------------|-----------|---------|---------------------------------------|
+| `inputPath`  | `string`  | —       | Path to the `.enc` file               |
+| `outputPath` | `string`  | —       | Path to write decrypted output to     |
+| `password`   | `string`  | —       | Password used during encryption       |
+| `gzip`       | `boolean` | `true`  | Decompress after decryption           |
+
+**Returns:** `Promise<void>`
+
+**Throws:** Same error codes as `decryptData`, plus automatic cleanup of `outputPath` on failure.
+
+```js
+await wilcocrypt.decryptFileStream('bigfile.zip.enc', 'bigfile.zip', 'passw0rd');
+```
+
+---
+
+### Internal Namespace (`_`)
+
+The `wilcocrypt._` namespace exposes internal helpers. These are not intended for normal use but are part of the public surface for advanced use cases and testing.
+
+| Member                  | Type       | Description                                              |
+|-------------------------|------------|----------------------------------------------------------|
+| `_.VERSION`             | `string`   | Current version string, embedded in every payload       |
+| `_.MIN_PASSWORD_LENGTH` | `number`   | Minimum accepted password length (6)                    |
+| `_.HEADER`              | `Buffer`   | 10-byte magic bytes identifying a WilcoCrypt payload    |
+| `_.WilcoCryptError`     | `class`    | The error class (also importable from TypeScript types)  |
+| `_.assertKeyAndIv(key, iv)` | `function` | Throws if key or IV are not valid Buffers of the right length |
+| `_.assertPassword(password)` | `function` | Throws `WEAK_PASSWORD` if password is too short   |
+| `_.constantTimeEqual(a, b)` | `function` | Constant-time Buffer comparison, returns `boolean`  |
+| `_.encryptData(plainData, key, iv)` | `function` | Raw AES-256-GCM encryption, returns `{ ciphertext, authTag }` |
+| `_.decryptData(cipherBuffer, authTagBuffer, key, iv)` | `function` | Raw AES-256-GCM decryption, returns `Buffer` |
+
+---
+
+## CLI Reference
+
+Install globally or use via `npx`:
+
+```bash
+npm install -g wilcocrypt
+wilcocrypt --help
+```
+
+### Options
+
+| Flag                     | Description                                         |
+|--------------------------|-----------------------------------------------------|
+| `-e, --encrypt <file>`   | Encrypt the given file, writes `<file>.enc`         |
+| `-d, --decrypt <file>`   | Decrypt the given `.enc` file                       |
+| `-o, --output <file>`    | Write decrypted output to `<file>` instead of stdout |
+| `--stdout`               | Explicitly write decrypted output to stdout (default) |
+| `--version`              | Show WilcoCrypt version                             |
+| `-h, --help`             | Show help                                           |
+
+Only one of `-e` or `-d` may be used at a time. The `--output` and `--stdout` flags are mutually exclusive. `--output` is only valid with `-d`.
+
+### Examples
+
+```bash
+# Encrypt a file
+wilcocrypt -e secret.txt
+# → prompts for password, writes secret.txt.enc
+
+# Decrypt to stdout (pipe-friendly)
+wilcocrypt -d secret.txt.enc
+# → prompts for password, writes to stdout
+
+# Decrypt to a file
+wilcocrypt -d secret.txt.enc -o secret.txt
+# → prompts for password, writes to secret.txt
+```
+
+Passwords are entered interactively with character masking (`*`). The CLI requires a TTY; piping passwords in is intentionally not supported.
+
+---
+
+## Binary Payload Format
+
+Every payload produced by WilcoCrypt v2.2.0 has the following binary layout:
+
+```
+[ HEADER    ]  10 bytes   — magic bytes: 23 9 12 3 15 3 18 25 16 20
+[ VERSION   ]  dynamic    — UTF-8 version string (e.g. "2.2.0"), 5 bytes for current version
+[ salt      ]  16 bytes   — random salt for scrypt key derivation
+[ iv        ]  12 bytes   — random IV for AES-256-GCM
+[ ciphertext]  variable   — AES-256-GCM encrypted (and optionally gzip-compressed) data
+[ authTag   ]  16 bytes   — GCM authentication tag
+```
+
+The auth tag is placed at the end to allow the streaming API to append it after the pipeline finishes, without needing to seek backwards in the output stream.
+
+> **Compatibility note:** The format changed between v2.1.x and v2.2.0. Files encrypted with v2.1.x cannot be decrypted with v2.2.0 and will throw a `VERSION_MISMATCH` or `INVALID_HEADER` error.
+
+---
+
+## Error Handling
+
+All errors thrown by WilcoCrypt are instances of `WilcoCryptError`, which extends `Error` with a `code` property.
+
+```js
+import wilcocrypt from 'wilcocrypt';
+const { WilcoCryptError } = wilcocrypt._;
+
+try {
+  wilcocrypt.decryptData(payload, 'wrong-password');
+} catch (err) {
+  if (err instanceof WilcoCryptError) {
+    console.error(err.code);    // e.g. DECRYPTION_FAILED
+    console.error(err.message); // human-readable
+  }
+}
+```
+
+### Error Codes
+
+| Code                    | Thrown by                        | Cause                                              |
+|-------------------------|----------------------------------|----------------------------------------------------|
+| `WEAK_PASSWORD`         | All public methods               | Password shorter than 6 characters                |
+| `INVALID_HEADER`        | `decryptData`, `decryptFile`, stream variants | Payload does not start with the WilcoCrypt magic bytes |
+| `VERSION_MISMATCH`      | `decryptData`, `decryptFile`, stream variants | Payload version does not match current version    |
+| `DECRYPTION_FAILED`     | `decryptData`, `decryptFile`, stream variants | Wrong password, tampered data, or corruption      |
+| `INVALID_FILE_EXTENSION`| `decryptFile`                    | File path does not end with `.enc`                |
+| `INVALID_KEY`           | `_.assertKeyAndIv`               | Key is not a 32-byte Buffer                       |
+| `INVALID_IV`            | `_.assertKeyAndIv`               | IV is not a 12-byte Buffer                        |
+| `NO_TTY`                | CLI password prompt              | stdin is not a TTY                                |
+
+---
+
+## TypeScript
+
+WilcoCrypt ships with `wilcocrypt.d.ts`. No `@types` package needed.
+
+```ts
+import wilcocrypt, { WilcoCryptError } from 'wilcocrypt';
+
+const encrypted: Buffer = wilcocrypt.encryptData(Buffer.from('hi'), 'passw0rd');
+
+// decryptFile overloads
+const buf: Buffer = wilcocrypt.decryptFile('file.enc', 'passw0rd');
+wilcocrypt.decryptFile('file.enc', 'passw0rd', 'output.txt'); // returns undefined
+
+// Streams
+await wilcocrypt.encryptFileStream('in.txt', 'in.txt.enc', 'passw0rd');
+await wilcocrypt.decryptFileStream('in.txt.enc', 'out.txt', 'passw0rd');
+```
+
+---
+
+## Security Notes
+
+- **Key derivation** uses [scrypt](https://nodejs.org/api/crypto.html#cryptoscryptsyncpassword-salt-keylen-options) with a 16-byte random salt generated fresh for every encryption. The same password will produce a different key each time.
+- **Authenticated encryption** via AES-256-GCM means any tampering with the ciphertext or auth tag will cause decryption to fail with `DECRYPTION_FAILED`.
+- **No password is stored** anywhere in the payload. There is no way to recover a lost password.
+- **The `gzip` flag must match** between encryption and decryption. If data was encrypted without compression (`gzip: false`), decryption must also use `gzip: false`.
+- See [SECURITY.md](./SECURITY.md) for the responsible disclosure policy.