🔒 lockbox (Zero-Dependency Edition)

lockbox is an open-source, lightweight, zero-dependency CLI utility designed for developers and development teams to securely encrypt, version-control, and distribute sensitive files (configuration files, .env profiles, private keys, certificates, or local databases) without exposing raw secrets to public repositories or unencrypted channels.

By leveraging AES-256-GCM authenticated encryption with memory-hard keys derived via the native Node.js scrypt algorithm, lockbox allows developers to transform any sensitive asset into a secure, self-contained, shareable cryptographic blob (.lockbox) that can be safely committed to Git or shared via team communication channels.

[!IMPORTANT] Zero-Dependency Security Mandate To guarantee complete immunity from supply-chain attacks (e.g., typosquatting, dependency confusion, malicious package updates, or compromised nested dependencies), lockbox is built strictly using the Node.js standard library. No third-party runtime dependencies are permitted.

🚀 Features

• Zero-Dependency Runtime: Completely immune to supply-chain package hijackings.
• AEAD Authenticated Encryption: AES-256-GCM guarantees absolute secrecy and payload integrity, instantly detecting and blocking tampering.
• Memory-Hard Key Derivation: Uses native scrypt ($N=16384, r=8, p=1$) key stretching, making brute-force GPU/ASIC cracking attacks mathematically infeasible.
• Proactive Memory Scrubbing: Internally fills sensitive key and password Buffers with zero bytes (buffer.fill(0)) immediately after cryptop executions to prevent secrets from lingering in V8 garbage collector heap memory.
• Safe-Git Protocol: Auto-climbs directories to locate repository root, normalized to forward slashes, and appends ignored assets to .gitignore within protective comment blocks to prevent accidental plain commits.
• Chunk-Based I/O Streams: Processes files in strict sequential chunk limits (up to 64KB RAM allocations) enabling constant O(1) memory footprints for arbitrary files of any size (gigabytes).
• Visual UX Polish: Includes friendly status colors and a custom non-blocking terminal loading spinner.

📦 Installation

Install globally via NPM:

npm install -g lockbox-cli

Or run directly on-the-fly without installation:

npx lockbox-cli --help

🛠️ CLI Usage & Command Suite

1. lockbox lock <file>

Encrypts a specified plain target file into an authenticated .lockbox binary envelope.

lockbox lock secrets.json [options]

Options:

• -p, --password <string>: Master password for key derivation. If omitted, triggers a secure, hidden prompt twice for confirmation.
• -o, --output <path>: Explicitly define the locked output path. Defaults to <file>.lockbox.
• --rm: Cryptographically overwrite (shred) the original plaintext target file after successful lock completion to prevent recovery.

Interactive Flow Example:

$ lockbox lock database.sqlite --rm
🔒 Enter Master Password to lock 'database.sqlite': **********
🔒 Confirm Master Password: **********

✔ Success: 'database.sqlite' encrypted into 'database.sqlite.lockbox'
✔ Auto-Protection: Added 'database.sqlite' to your local .gitignore
✔ Shredded: Safely deleted original plaintext asset.

2. lockbox unlock <file>

Decrypts a .lockbox envelope back into its raw plaintext state.

lockbox unlock secrets.json.lockbox [options]

Options:

• -p, --password <string>: Master password for decryption. If omitted, triggers a single secure prompt.
• -o, --output <path>: Explicitly define the decrypted output path. Defaults to stripping the .lockbox extension.

Interactive Flow Example:

$ lockbox unlock database.sqlite.lockbox
🔑 Enter Master Password to unlock: **********

✔ Success: Decrypted 'database.sqlite.lockbox' -> 'database.sqlite'
✔ [Integrity Check: PASSED]

3. lockbox env (Specialized Macro)

A high-level utility macro specifically optimized for managing .env environment credential files across workspaces.

• lockbox env push: Automatically verifies local .env, prompts securely for a password, creates .env.lockbox, adds .env to .gitignore, and queries if you'd like to shred the local plain .env file.

  lockbox env push

• lockbox env pull: Instantly prompts for your master password and reconstitutes .env from .env.lockbox in your workspace directory.

  lockbox env pull

🔒 Cryptographic Blueprint

| Component | Technology | Specification | | :--- | :--- | :--- | | KDF | scrypt | Memory-hard key derivation function ($N=16384, r=8, p=1$) | | KDF Salt | Cryptographic Random | Unique 32-byte salt generated per lock operation | | Cipher Mode | AES-256-GCM | Authenticated Encryption with Associated Data (AEAD) | | Nonce (IV) | Cryptographic Random | Unique 12-byte IV generated per lock operation | | Auth Tag | GCM Tag | 16-byte authenticity tag to prevent tampering | | Envelope Layout| Self-Contained | [Salt (32B)] + [IV (12B)] + [Tag (16B)] + [Ciphertext] |

📄 License

Distributed under the MIT License.

Copyright (c) 2026 lockbox-cli Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.