keebox 0.9.0 → 0.9.2

package/README.md

@@ -10,9 +10,17 @@
 </p>
 
 <p align="center">
-  <a href="https://keybox.eissa.top">Website</a> ·
+  <a href="https://www.npmjs.com/package/keebox"><img src="https://img.shields.io/npm/v/keebox?color=f5a524&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/keebox"><img src="https://img.shields.io/npm/dm/keebox?color=f5a524" alt="npm downloads"></a>
+  <a href="https://opensource.org/license/mit"><img src="https://img.shields.io/badge/license-MIT-f5a524" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-f5a524?logo=nodedotjs&logoColor=white" alt="node >= 18">
+  <img src="https://img.shields.io/badge/dependencies-0-7ccf8a" alt="zero dependencies">
+</p>
+
+<p align="center">
+  <a href="https://keebox.eissa.top">Website</a> ·
   <a href="#get-started">Get started</a> ·
-  <a href="#commands-using-the-pass-alias">Commands</a> ·
+  <a href="#commands">Commands</a> ·
   <a href="#encryption">Security</a>
 </p>
 
@@ -27,7 +35,7 @@ Most password managers ask you to trust them with everything: your passwords sit
 - **Nothing in the cloud.** KeeBox never touches the network: no sync server to breach, no telemetry, no account to phish. Your encrypted vault only exists where you put it.
 - **Strong, standard encryption.** Every password, login and note is encrypted with AES-256-GCM. The key is locked behind your master password with scrypt, which makes guessing slow and expensive. Tampered or damaged entries are detected and refused, never silently decrypted into garbage.
 - **A recovery phrase, like a crypto wallet.** Lost your credentials file or forgot your master password? A 12-word recovery phrase gets you back in. Without the phrase or the password, nobody can open the vault, not even the author of KeeBox.
-- **Zero dependencies.** No `npm install` and no third-party packages, so there's no supply chain to compromise. The whole tool is about 1,300 lines of plain Node.js that you can read and audit in an afternoon.
+- **Zero dependencies.** No third-party packages, so there's no supply chain to compromise. The whole tool is about 1,300 lines of plain Node.js that you can read and audit in an afternoon.
 - **Portable.** Copy the folder plus a Node.js binary to a USB drive and it runs on Linux, macOS, Windows and Android (Termux), no installation needed.
 - **Fast from the terminal.** Generate strong passwords, find accounts by any field, and copy a password to the clipboard. It's wiped automatically after 20 seconds.
 - **Yours to keep.** Export everything to CSV whenever you want, import accounts from CSV, and check your vault for damage. Open source and MIT licensed.
@@ -39,9 +47,22 @@ Most password managers ask you to trust them with everything: your passwords sit
 Requires Node.js 18+.
 
 ```
-git clone https://github.com/eissapk/keybox.git keebox
+npm install -g keebox
+keebox -h
+```
+
+Your vault (`db.json` + `credentials.json`) is kept in `~/.keebox/`, outside the npm folder, so updating or uninstalling KeeBox never touches it. To keep it somewhere else (an encrypted drive, a backed-up folder...), set `KEEBOX_HOME`:
+
+```
+export KEEBOX_HOME=/path/to/vault-folder # in your .bashrc / .zshrc
+```
+
+Or run it from source, without installing (the vault then lives in the project folder):
+
+```
+git clone https://github.com/eissapk/keebox.git
 cd keebox # no npm install needed, there are no dependencies
-node index.js -h
+node bin/index.js -h
 ```
 
 Clipboard: macOS and Windows/WSL work as is, Linux needs `xclip` (X11) or `wl-clipboard` (Wayland). On Android (Termux) passwords are printed instead of copied.
@@ -51,9 +72,10 @@ Clipboard: macOS and Windows/WSL work as is, Linux needs `xclip` (X11) or `wl-cl
 ```
 ├── assets
 │   └── logo.svg
+├── bin
+│   └── index.js         # CLI entry (the `keebox` command): commands + master password prompt
 ├── credentials.json     # created on first run (master password lock), not in git
 ├── db.json              # created on first run (accounts + recovery lock), not in git
-├── index.js             # CLI entry: commands + master password prompt
 ├── node                 # optional, for a portable copy (see below), not in git
 │   ├── linux/node
 │   ├── mac/node
@@ -86,9 +108,11 @@ Clipboard: macOS and Windows/WSL work as is, Linux needs `xclip` (X11) or `wl-cl
     └── wordlist.js      # BIP39 English wordlist
 ```
 
+`db.json` / `credentials.json` sit in the project folder when run from source or a portable copy, in `~/.keebox/` when installed with npm, or in `$KEEBOX_HOME` when it's set.
+
 ##### Make it portable (USB flash)
 
-Copy the project with a Node.js binary per OS, so it runs on machines without Node installed:
+Copy the project with a Node.js binary per OS, so it runs on machines without Node installed. The vault is kept next to it, on the flash drive:
 
 ```
 cp -r /path/to/project /path/to/usb-flash
@@ -98,46 +122,47 @@ cp "$(command -v node)" /path/to/usb-flash/node/linux/node # repeat for mac/node
 Run it from the flash drive:
 
 ```
-/path/to/usb-flash/node/linux/node /path/to/usb-flash/index.js -h
+/path/to/usb-flash/node/linux/node /path/to/usb-flash/bin/index.js -h
 ```
 
 Or add an alias in your `.bashrc` / `.zshrc`, and use it anywhere:
 
 ```
-alias pass='node /path/to/usb-flash/index.js'
-pass --help
-pass --version
+alias keebox='node /path/to/usb-flash/bin/index.js'
+keebox --help
+keebox --version
 ```
 
-##### Commands (using the `pass` alias)
+##### Commands
 
 ```
-pass get # list all accounts
-pass get --id 2 # show account with id 2
-pass get --name google # show accounts whose name contains "google"
-pass get --id 2 --cp # copy its password to the clipboard (auto-cleared after 20s)
-pass get --id 2 --show # show its login/notes
-pass get --id 2 --edit # update it (Enter = keep a value, '-' = clear it)
-pass get --id 2 --rm # delete it
-pass add --name google --username foo@gmail.com --url www.google.com # add an account (asks for its password)
-pass add --name github --username foo --url github.com --login foo@mail.com --notes "2FA via phone" # with login/notes (encrypted)
-pass make --size 20 # generate a random strong password of 20 chars
-pass export # export all accounts, decrypted, to keebox-export-<date>.csv
-pass export --name google --out google.csv # export matching accounts to google.csv
-pass import --file accounts.csv # add accounts from a csv (same columns as export; id is ignored, duplicates skipped)
-pass check # damage check: lists accounts that are broken or can't be decrypted (read-only, exit code 1 if any)
-pass recovery # create (or replace) the 12-word recovery phrase
-pass recover # lost credentials.json / forgot the master password: unlock with the recovery phrase, set a new master password
+keebox get # list all accounts
+keebox get --id 2 # show account with id 2
+keebox get --name google # show accounts whose name contains "google"
+keebox get --id 2 --cp # copy its password to the clipboard (auto-cleared after 20s)
+keebox get --id 2 --show # show its login/notes
+keebox get --id 2 --edit # update it (Enter = keep a value, '-' = clear it)
+keebox get --id 2 --rm # delete it
+keebox add --name google --username foo@gmail.com --url www.google.com # add an account (asks for its password)
+keebox add --name github --username foo --url github.com --login foo@mail.com --notes "2FA via phone" # with login/notes (encrypted)
+keebox make --size 20 # generate a random strong password of 20 chars
+keebox export # export all accounts, decrypted, to keebox-export-<date>.csv
+keebox export --name google --out google.csv # export matching accounts to google.csv
+keebox import --file accounts.csv # add accounts from a csv (same columns as export; id is ignored, duplicates skipped)
+keebox check # damage check: lists accounts that are broken or can't be decrypted (read-only, exit code 1 if any)
+keebox recovery # create (or replace) the 12-word recovery phrase
+keebox recover # lost credentials.json / forgot the master password: unlock with the recovery phrase, set a new master password
+keebox master # create or change the master password
 ```
 
 Exported CSV files are **not encrypted**, delete them when you're done.
 
 ##### Create / change master password
 
-On a new (empty) vault, the first `pass add` / `pass get` asks you to create one. To create it yourself, or change it later (asks the current one first; `db.json` stays as is, and the recovery phrase keeps working):
+On a new (empty) vault, the first `keebox add` / `keebox get` asks you to create one. To create it yourself, or change it later (asks the current one first; `db.json` stays as is, and the recovery phrase keeps working):
 
 ```
-node utils/config.js
+keebox master
 ```
 
 ##### Encryption
@@ -147,14 +172,14 @@ Each password, login and notes is encrypted (AES-256-GCM) with one random 256-bi
 | Where | Locked with | Opened by |
 |---|---|---|
 | `credentials.json` → `{ salt, n, key }` | scrypt(master password, salt) + AES-256-GCM | the master password |
-| `db.json` → `recovery: { salt, n, key }` | scrypt(12-word phrase, salt) + AES-256-GCM | the recovery phrase (`pass recover`) |
+| `db.json` → `recovery: { salt, n, key }` | scrypt(12-word phrase, salt) + AES-256-GCM | the recovery phrase (`keebox recover`) |
 
 What gets you into the accounts:
 
 | You have | Access? |
 |---|---|
 | `db.json` + `credentials.json` + master password | yes (normal use) |
-| `db.json` + recovery phrase | yes: `pass recover` sets a new master password and writes a new `credentials.json` |
+| `db.json` + recovery phrase | yes: `keebox recover` sets a new master password and writes a new `credentials.json` |
 | `db.json` + master password, but no `credentials.json` | **no**: the master password only opens `credentials.json` (restore `credentials.json.bak` or a backup) |
 | `db.json` alone | **no**, for anyone: it would mean guessing a 128-bit phrase or a 256-bit key |
 
@@ -162,15 +187,15 @@ So keep `db.json` and `credentials.json` together and backed up, choose a strong
 
 ##### Recovery phrase (emergency key)
 
-`pass recovery` makes a 12-word phrase (BIP39 English words, like a crypto wallet seed: 128 random bits + checksum) and locks the same vault key with it into `db.json`. The phrase itself is never saved, it's shown once: write it down, then type it back to confirm.
+`keebox recovery` makes a 12-word phrase (BIP39 English words, like a crypto wallet seed: 128 random bits + checksum) and locks the same vault key with it into `db.json`. The phrase itself is never saved, it's shown once: write it down, then type it back to confirm.
 
-If `credentials.json` is deleted or you forget the master password, `pass recover` asks for the 12 words (any case/spacing; typos and swapped words are caught by the checksum), unlocks the vault key and lets you set a new master password. Only `credentials.json` is written, `db.json` isn't changed, and the same phrase keeps working afterwards. Running `pass recovery` again replaces the phrase (the old one stops working, except against an older `db.json.bak`).
+If `credentials.json` is deleted or you forget the master password, `keebox recover` asks for the 12 words (any case/spacing; typos and swapped words are caught by the checksum), unlocks the vault key and lets you set a new master password. Only `credentials.json` is written, `db.json` isn't changed, and the same phrase keeps working afterwards. Running `keebox recovery` again replaces the phrase (the old one stops working, except against an older `db.json.bak`).
 
 Anyone with the phrase + `db.json` can read every account, so guard it like the master password.
 
 ##### Files
 
-`db.json` (`recovery` is `null` until you run `pass recovery`):
+`db.json` (`recovery` is `null` until you run `keebox recovery`):
 
 ```json
 {
@@ -197,12 +222,12 @@ Anyone with the phrase + `db.json` can read every account, so guard it like the
 { "salt": "...", "n": 32768, "key": "iv.tag.data" }
 ```
 
-Both are created automatically if missing, and every save keeps the previous version as `db.json.bak` / `credentials.json.bak`. If `credentials.json` is missing but `db.json` has data, KeeBox won't create a new master password (that would make a new vault key and lock out the existing accounts); it asks you to run `pass recover` or restore `credentials.json.bak` instead.
+Both are created automatically if missing, and every save keeps the previous version as `db.json.bak` / `credentials.json.bak`. If `credentials.json` is missing but `db.json` has data, KeeBox won't create a new master password (that would make a new vault key and lock out the existing accounts); it asks you to run `keebox recover` or restore `credentials.json.bak` instead.
 
 ##### Decryption flow
 
 ```
-                         pass get --id 11 --cp
+                        keebox get --id 11 --cp
                                     │
                                     ▼
                     ┌───────────────────────────────┐
@@ -269,7 +294,7 @@ Both are created automatically if missing, and every save keeps the previous ver
 ##### Recovery flow
 
 ```
-                               pass recover
+                              keebox recover
                                     │
                                     ▼
                     ┌───────────────────────────────┐
@@ -296,10 +321,10 @@ Both are created automatically if missing, and every save keeps the previous ver
 
 | Step | File | Uses |
 |---|---|---|
-| Ask for or create the master password | `index.js` → `askMaster`, `utils/config.js` → `createMaster` | master password |
+| Ask for or create the master password | `bin/index.js` → `askMaster`, `utils/config.js` → `createMaster` | master password |
 | Master password → vault key | `utils/vault.js` → `unlock` | `credentials.json` `salt`, `n`, `key` |
-| Create the recovery phrase (`pass recovery`) | `options/recovery.js` → `createRecovery`, `utils/vault.js` → `makeRecovery`, `utils/mnemonic.js` | `db.json` `recovery` |
-| Recovery phrase → vault key (`pass recover`) | `options/recovery.js` → `recoverVault`, `utils/vault.js` → `recover` | `db.json` `recovery` |
+| Create the recovery phrase (`keebox recovery`) | `options/recovery.js` → `createRecovery`, `utils/vault.js` → `makeRecovery`, `utils/mnemonic.js` | `db.json` `recovery` |
+| Recovery phrase → vault key (`keebox recover`) | `options/recovery.js` → `recoverVault`, `utils/vault.js` → `recover` | `db.json` `recovery` |
 | Vault key → account password | `utils/index.js` → `decrypt` (called from `options/get.js` → `copyEntry`) | `iv`, `tag`, `data` |
 
 ##### Tests

package/{index.js → bin/index.js}

@@ -1,7 +1,8 @@
-const { mkPass, askPassword, loadData, copyOrPrint, run, FIELDS, SECRET_FIELDS, log, hasMaster, unlock, createMaster, parseArgs } = require("./utils");
+#!/usr/bin/env node
+const { mkPass, askPassword, loadData, copyOrPrint, run, FIELDS, SECRET_FIELDS, log, hasMaster, unlock, createMaster, changeMaster, parseArgs } = require("../utils");
 const crypto = require("crypto");
-const pkgJSON = require("./package.json");
-const { getEntry, addEntry, exportEntries, importEntries, checkDb, createRecovery, recoverVault } = require("./options");
+const pkgJSON = require("../package.json");
+const { getEntry, addEntry, exportEntries, importEntries, checkDb, createRecovery, recoverVault } = require("../options");
 
 run(main);
 
@@ -29,9 +30,9 @@ async function main() {
       ["--out <file>", "CSV file to write (default: keebox-export-<date>.csv) - use it with 'export' command"],
       ["--file <file>", "CSV file to read (columns: name,password + optional url,username,login,notes,created,updated) - use it with 'import' command"],
     ],
-    commands: { add: "Add account", get: "display account(s)", make: "Generate a password", export: "Export account(s) as decrypted CSV (filter with --id/--name/...)", import: "Import account(s) from a CSV file (e.g. one made by 'export')", check: "Damage check: find accounts that are broken or can't be decrypted (changes nothing)", recovery: "Create (or replace) the 12-word recovery phrase", recover: "Lost credentials.json / forgot the master password: unlock with the recovery phrase and set a new master password" },
+    commands: { add: "Add account", get: "display account(s)", make: "Generate a password", export: "Export account(s) as decrypted CSV (filter with --id/--name/...)", import: "Import account(s) from a CSV file (e.g. one made by 'export')", check: "Damage check: find accounts that are broken or can't be decrypted (changes nothing)", recovery: "Create (or replace) the 12-word recovery phrase", recover: "Lost credentials.json / forgot the master password: unlock with the recovery phrase and set a new master password", master: "Create or change the master password (accounts and recovery phrase keep working)" },
   });
-  if (parsed) await { add, get, make, export: exportCsv, import: importCsv, check, recovery, recover }[parsed.command](parsed.opts, db, cred);
+  if (parsed) await { add, get, make, export: exportCsv, import: importCsv, check, recovery, recover, master }[parsed.command](parsed.opts, db, cred);
 }
 
 // ask master password -> vault key, or null
@@ -106,3 +107,7 @@ async function recovery(opts, db, cred) {
 async function recover(opts, db, cred) {
   await recoverVault(db, cred);
 }
+
+async function master(opts, db, cred) {
+  await changeMaster(db, cred);
+}

package/package.json

@@ -1,20 +1,25 @@
 {
   "name": "keebox",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "KeeBox is an offline password manager that lives in your terminal",
-  "main": "index.js",
+  "bin": {
+    "keebox": "./bin/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "test": "node --test"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/eissapk/keybox.git"
+    "url": "git+https://github.com/eissapk/keebox.git"
   },
   "keywords": [],
   "author": "Eissa Saber",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/eissapk/keybox/issues"
+    "url": "https://github.com/eissapk/keebox/issues"
   },
-  "homepage": "https://github.com/eissapk/keybox#readme"
+  "homepage": "https://github.com/eissapk/keebox#readme"
 }

package/utils/config.js

@@ -1,14 +1,17 @@
 const { askPassword, loadData, saveOrReport, run, credPath, log, lockVault, hasMaster, unlock } = require("./index");
 const crypto = require("crypto");
 
-// usage: node utils/config.js   -> create the master password, or change it
+// usage: keebox master (or node utils/config.js)   -> create the master password, or change it
 if (require.main === module) run(main);
-module.exports = { createMaster };
+module.exports = { createMaster, changeMaster };
 
 async function main() {
   const data = loadData();
-  if (!data) return;
-  const { db, cred } = data;
+  if (data) await changeMaster(data.db, data.cred);
+}
+
+// create the master password, or change it (asks the current one first)
+async function changeMaster(db, cred) {
   if (!hasMaster(cred)) {
     // a new vault key would make the existing accounts unreadable
     if (db.accounts.length || db.recovery) return log.error("credentials.json is missing, but db.json has data. Run 'recover' with your recovery phrase, or restore credentials.json.bak");

package/utils/index.js

@@ -12,8 +12,19 @@ const prompt = require("./prompt");
 const drawTable = require("./table");
 const parseArgs = require("./cli");
 
-const dbPath = path.resolve(__dirname, "../db.json");
-const credPath = path.resolve(__dirname, "../credentials.json");
+// where db.json + credentials.json live:
+// - $KEEBOX_HOME when set
+// - ~/.keebox when installed with npm (inside node_modules, which npm wipes on update/uninstall)
+// - the project folder otherwise (git clone / portable USB copy)
+function dataDir() {
+  if (process.env.KEEBOX_HOME) return path.resolve(process.env.KEEBOX_HOME);
+  const appDir = path.resolve(__dirname, "..");
+  if (appDir.split(path.sep).includes("node_modules")) return path.join(require("os").homedir(), ".keebox");
+  return appDir;
+}
+const dir = dataDir();
+const dbPath = path.join(dir, "db.json");
+const credPath = path.join(dir, "credentials.json");
 
 // cryptographically secure, exact length, at least one char of each class (length >= 4)
 function mkPass(length) {
@@ -67,7 +78,8 @@ function decryptField(entry, field, key) {
 function saveJson(file, data) {
   const fs = require("fs");
   const tmp = file + ".tmp";
-  const fd = fs.openSync(tmp, "w");
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const fd = fs.openSync(tmp, "w", 0o600);
   try {
     fs.writeFileSync(fd, JSON.stringify(data, null, 2));
     fs.fsyncSync(fd);

package/utils/prompt.js

@@ -1,12 +1,12 @@
 // minimal inquirer replacement, public Node APIs only
 // await prompt([{ type: "input" | "password" | "confirm", name, message, default }]) -> answers
 // - interactive (stdin is a terminal): readline for input/confirm, raw-mode reader for passwords (masked with "•")
-// - piped stdin: one shared line queue, so answers can be scripted: printf 'pw\ny\n' | node index.js get --id 1 --rm
+// - piped stdin: one shared line queue, so answers can be scripted: printf 'pw\ny\n' | keebox get --id 1 --rm
 // - Ctrl+C exits 130; Ctrl+D / end of input cancels with exit 1 (never auto-answers, e.g. "delete? (Y/n)")
 const readline = require("readline");
 const readlinePromises = require("readline/promises");
 
-// prompts go to the terminal even when stdout is redirected (node index.js get > list.txt)
+// prompts go to the terminal even when stdout is redirected (keebox get > list.txt)
 function promptOut() {
   return process.stdout.isTTY || !process.stderr.isTTY ? process.stdout : process.stderr;
 }