keebox 0.0.0-stage → 0.9.1

package/README.md

@@ -1,3 +1,317 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/logo.svg" alt="KeeBox logo" width="120">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">KeeBox</h1>
+
+<p align="center">
+  <b>KeeBox</b> is an offline password manager that lives in your terminal.<br>
+  Your passwords. Your keys. Your files.
+</p>
+
+<p align="center">
+  <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="#encryption">Security</a>
+</p>
+
+---
+
+Most password managers ask you to trust them with everything: your passwords sit on their servers, behind their account system, their app updates and their subscription. When one of them is breached, changes its pricing or shuts down, your vault goes with it.
+
+**KeeBox** takes the opposite approach. It's a password manager with no server and no account. Your vault is two small JSON files that you own: keep them on your laptop, or carry them on a USB stick and run KeeBox on any machine you plug into.
+
+##### Why switch to **KeeBox**
+
+- **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.
+- **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.
+
+> **What you trade:** KeeBox doesn't autofill in your browser or sync between devices for you. You're in charge of your files and backups, and that's the point.
+
+##### Get started
+
+Requires Node.js 18+.
+
+```
+git clone https://github.com/eissapk/keybox.git keebox
+cd keebox # no npm install needed, there are no dependencies
+node 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.
+
+##### Structure
+
+```
+├── assets
+│   └── logo.svg
+├── 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
+│   └── win/node.exe
+├── options              # one file per command
+│   ├── add.js
+│   ├── check.js
+│   ├── delete.js
+│   ├── export.js
+│   ├── get.js
+│   ├── import.js
+│   ├── index.js
+│   ├── recovery.js      # 'recovery' + 'recover'
+│   └── update.js
+├── package.json
+├── README.md
+├── test                 # npm test
+└── utils
+    ├── cli.js           # argument parser
+    ├── colors.js        # KeeBox palette (truecolor / 256 / 16 colors)
+    ├── config.js        # create / change the master password
+    ├── csv.js
+    ├── fields.js
+    ├── index.js         # encrypt/decrypt, load/save db, clipboard, helpers
+    ├── log.js           # message styles (✓ / [+] / [-] / [!] / ✗)
+    ├── mnemonic.js      # 12-word recovery phrase (BIP39)
+    ├── prompt.js
+    ├── table.js
+    ├── vault.js         # vault key locking (master password / recovery phrase)
+    └── wordlist.js      # BIP39 English wordlist
+```
+
+##### Make it portable (USB flash)
+
+Copy the project with a Node.js binary per OS, so it runs on machines without Node installed:
+
+```
+cp -r /path/to/project /path/to/usb-flash
+cp "$(command -v node)" /path/to/usb-flash/node/linux/node # repeat for mac/node and win/node.exe
+```
+
+Run it from the flash drive:
+
+```
+/path/to/usb-flash/node/linux/node /path/to/usb-flash/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
+```
+
+##### Commands (using the `pass` alias)
+
+```
+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
+```
+
+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):
+
+```
+node utils/config.js
+```
+
+##### Encryption
+
+Each password, login and notes is encrypted (AES-256-GCM) with one random 256-bit **vault key** (login/notes show as `***` in the table, read them with `--show`). The vault key is never stored as is, only locked, in two independent places:
+
+| 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`) |
+
+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` + 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 |
+
+So keep `db.json` and `credentials.json` together and backed up, choose a strong master password (a copied `credentials.json` + `db.json` is only as safe as it), and keep the recovery phrase offline.
+
+##### 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.
+
+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`).
+
+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`):
+
+```json
+{
+  "recovery": { "salt": "...", "n": 32768, "key": "iv.tag.data" },
+  "accounts": [
+    {
+      "id": 1,
+      "name": "github",
+      "url": "github.com",
+      "username": "foo",
+      "login": "iv.tag.data",
+      "notes": "iv.tag.data",
+      "password": "iv.tag.data",
+      "created": "2026-01-01T00:00:00.000Z",
+      "updated": "2026-01-01T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+`credentials.json` (`{}` until a master password is created):
+
+```json
+{ "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.
+
+##### Decryption flow
+
+```
+                         pass get --id 11 --cp
+                                    │
+                                    ▼
+                    ┌───────────────────────────────┐
+                    │ Master password exists?       │  (credentials.json)
+                    └───────────────┬───────────────┘
+                         no │               │ yes
+                            ▼               ▼
+         ┌──────────────────────────┐   ┌──────────────────────────┐
+         │ db.json has data?        │   │ Ask MASTER PASSWORD      │
+         │ yes: stop, "run 'recover'│   │ (trim spaces)            │
+         │  or restore .bak"        │   └────────────┬─────────────┘
+         │ no: choose + re-type,    │                │
+         │ new random vault key,    │                │
+         │ save it, continue ─────┐ │                ▼
+         └────────────────────────┼─┘
+                                  │      ╔═══════════════════════════════╗
+                                  │      ║ PART 1: MASTER PASSWORD       ║
+                                  │      ║ credentials.json {salt,n,key} ║
+                                  │      ╚═══════════════╤═══════════════╝
+                                  │                      ▼
+                                  │      ┌──────────────────────────────┐
+                                  │      │ scrypt(password, salt, n)    │
+                                  │      │       → temporary key        │
+                                  │      └──────────────┬───────────────┘
+                                  │                     ▼
+                                  │      ┌──────────────────────────────┐
+                                  │      │ AES-GCM decrypt "key"        │
+                                  │      │ (iv.tag.data)                │
+                                  │      └───────┬──────────────┬───────┘
+                                  │      tag OK  │              │ tag fails
+                                  │              │              ▼
+                                  │              │   ┌──────────────────────┐
+                                  │              │   │ "Wrong password"     │──► stop
+                                  │              │   └──────────────────────┘
+                                  │              ▼
+                                  │      ┌──────────────────────────────┐
+                                  └─────►│   VAULT KEY (in memory only) │
+                                         └──────────────┬───────────────┘
+                                                        ▼
+                                         ╔═══════════════════════════════╗
+                                         ║ PART 2: ACCOUNT PASSWORD      ║
+                                         ╚═══════════════╤═══════════════╝
+                                                         ▼
+                                         ┌──────────────────────────────┐
+                                         │ Filter db.json accounts      │
+                                         │ exactly 1 match? else stop   │
+                                         └──────────────┬───────────────┘
+                                                        ▼
+                                         ┌──────────────────────────────┐
+                                         │ split "iv.tag.data"          │
+                                         │ AES-GCM decrypt with         │
+                                         │ VAULT KEY + iv + tag         │
+                                         └───────┬──────────────┬───────┘
+                                         tag OK  │              │ fails
+                                                 ▼              ▼
+                                  ┌───────────────────────┐  ┌───────────────────┐
+                                  │ plain password        │  │ "empty or damaged"│
+                                  │ Termux: print it      │  └───────────────────┘
+                                  │ else: clipboard,      │
+                                  │ auto-clear in 20s     │
+                                  └───────────────────────┘
+```
+
+##### Recovery flow
+
+```
+                               pass recover
+                                    │
+                                    ▼
+                    ┌───────────────────────────────┐
+                    │ db.json has a recovery lock?  │──► no: stop
+                    └───────────────┬───────────────┘
+                                    ▼
+                    ┌───────────────────────────────┐
+                    │ Ask RECOVERY PHRASE (12 words)│
+                    │ 12 known words + checksum OK? │──► no: "Invalid recovery phrase"
+                    └───────────────┬───────────────┘
+                                    ▼
+                    ┌───────────────────────────────┐
+                    │ scrypt(phrase, salt, n)       │
+                    │ AES-GCM decrypt recovery.key  │──► tag fails: "Wrong recovery phrase"
+                    └───────────────┬───────────────┘
+                                    ▼
+                    ┌───────────────────────────────┐
+                    │ VAULT KEY (in memory only)    │
+                    │ choose new MASTER PASSWORD    │
+                    │ → writes credentials.json     │
+                    │ (db.json unchanged)           │
+                    └───────────────────────────────┘
+```
+
+| Step | File | Uses |
+|---|---|---|
+| Ask for or create the master password | `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` |
+| Vault key → account password | `utils/index.js` → `decrypt` (called from `options/get.js` → `copyEntry`) | `iv`, `tag`, `data` |
+
+##### Tests
+
+```
+npm test
+```

package/assets/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path d="M16 4 28 10 16 16 4 10z" fill="#f9c879"/><path d="M4 10 16 16v13L4 23z" fill="#ea9a35"/><path d="M16 16 28 10v13l-12 6z" fill="#b9661b"/><path d="M8.4 12.2 20.4 6.2 23.6 7.8 11.6 13.8z" fill="#fff4de"/><path d="M8.4 12.2 11.6 13.8v13l-3.2-1.6z" fill="#f8deb0"/><g transform="matrix(1 -0.5 0 1 0 0)"><rect x="18.6" y="29.4" width="7.2" height="4.6" rx=".7" fill="#fff4de"/><g fill="#7a3f0c"><circle cx="20.1" cy="31.7" r=".6"/><circle cx="21.5" cy="31.7" r=".6"/><circle cx="22.9" cy="31.7" r=".6"/><circle cx="24.3" cy="31.7" r=".6"/></g></g><path d="M4 10 16 4l12 6" fill="none" stroke="#fff" stroke-opacity=".45" stroke-width=".6" stroke-linejoin="round"/><path d="M4 10 16 16 28 10M16 16v13" fill="none" stroke="#7a3f0c" stroke-opacity=".25" stroke-width=".5" stroke-linejoin="round"/></svg>

package/index.js

@@ -0,0 +1,108 @@
+const { mkPass, askPassword, loadData, copyOrPrint, run, FIELDS, SECRET_FIELDS, log, hasMaster, unlock, createMaster, parseArgs } = require("./utils");
+const crypto = require("crypto");
+const pkgJSON = require("./package.json");
+const { getEntry, addEntry, exportEntries, importEntries, checkDb, createRecovery, recoverVault } = require("./options");
+
+run(main);
+
+async function main() {
+  // connect to db
+  const data = loadData();
+  if (!data) return;
+  const { db, cred } = data;
+
+  const parsed = parseArgs(process.argv.slice(2), {
+    version: pkgJSON.version,
+    description: "KeeBox CLI Tool (" + pkgJSON.version + ")",
+    options: [
+      ["--id <id>", "Include account id - use it with 'get/add' commands"],
+      ["--name <name>", "Include account name - use it with 'get/add' commands"],
+      ["--url <url>", "Include account url - use it with 'get/add' commands"],
+      ["--username <username>", "Include account username - use it with 'get/add' commands"],
+      ["--login <login>", "Include account login (encrypted) - use it with 'add' command"],
+      ["--notes <notes>", "Include account notes (encrypted) - use it with 'add' command"],
+      ["--cp", "Copy account password to clipboard - use it with 'get' command"],
+      ["--show", "Show account login/notes - use it with 'get' command"],
+      ["--edit", "Update account in db - use it with 'get' command"],
+      ["--rm", "Delete account in db - use it with 'get' command"],
+      ["--size <size>", "Password length - use it with 'make' command"],
+      ["--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" },
+  });
+  if (parsed) await { add, get, make, export: exportCsv, import: importCsv, check, recovery, recover }[parsed.command](parsed.opts, db, cred);
+}
+
+// ask master password -> vault key, or null
+async function askMaster(cred, db) {
+  if (!hasMaster(cred)) {
+    // a new vault key would make the existing accounts unreadable
+    if (db.accounts.length || db.recovery) {
+      log.error("credentials.json is missing or has no master password, but db.json has data.");
+      log.warnErr("Run 'recover' with your recovery phrase, or restore credentials.json.bak");
+      return null;
+    }
+    log.warn("No MASTER PASSWORD yet, let's create one.");
+    const key = await createMaster(cred, crypto.randomBytes(32));
+    if (key) log.hint("Tip: run 'recovery' to create a 12-word recovery phrase, in case credentials.json is lost");
+    return key;
+  }
+  const key = unlock((await askPassword("MASTER PASSWORD:")).trim(), cred);
+  if (!key) log.error("Wrong password!");
+  return key;
+}
+
+async function add(opts, db, cred) {
+  for (const f of ["name", "url", "username"]) if (!opts[f]) return log.error("Missing --" + f + " argument!");
+  const entry = {};
+  FIELDS.forEach((f) => (entry[f] = opts[f] || ""));
+
+  const key = await askMaster(cred, db);
+  if (key) await addEntry(db, entry, key);
+}
+
+async function get(opts, db, cred) {
+  for (const f of SECRET_FIELDS) if (opts[f]) return log.error("Can't search by --" + f + ", it's encrypted (read it with --show)");
+  const query = {};
+  ["id", ...FIELDS].forEach((f) => opts[f] && (query[f] = opts[f]));
+
+  const key = await askMaster(cred, db);
+  if (key) await getEntry(db, query, opts, key);
+}
+
+async function make(opts) {
+  if (!opts.size) return log.error("Missing --size argument!");
+  const length = Number(opts.size);
+  if (!Number.isInteger(length) || length < 4 || length > 1024) return log.error("--size must be a number between 4 and 1024");
+  await copyOrPrint(mkPass(length), "", true);
+}
+
+async function exportCsv(opts, db, cred) {
+  for (const f of SECRET_FIELDS) if (opts[f]) return log.error("Can't filter by --" + f + ", it's encrypted");
+  const query = {};
+  ["id", ...FIELDS].forEach((f) => opts[f] && (query[f] = opts[f]));
+  const file = opts.out || "keebox-export-" + new Date().toISOString().slice(0, 10) + ".csv";
+  await exportEntries(db, query, file, () => askMaster(cred, db));
+}
+
+async function importCsv(opts, db, cred) {
+  if (!opts.file) return log.error("Missing --file argument!");
+  await importEntries(db, opts.file, () => askMaster(cred, db));
+}
+
+async function check(opts, db, cred) {
+  await checkDb(db, cred, async () => {
+    const key = unlock((await askPassword("MASTER PASSWORD:")).trim(), cred);
+    if (!key) log.error("Wrong password!");
+    return key;
+  });
+}
+
+async function recovery(opts, db, cred) {
+  await createRecovery(db, () => askMaster(cred, db));
+}
+
+async function recover(opts, db, cred) {
+  await recoverVault(db, cred);
+}

package/options/add.js

@@ -0,0 +1,16 @@
+const { askPassword, encrypt, decryptField, saveOrReport, nextEntryId, dbPath, SECRET_FIELDS, log } = require("../utils");
+
+async function addEntry(db, entry, key) {
+  const entryExists = db.accounts.some((obj) => ["name", "url", "username"].every((f) => entry[f] == obj[f]) && entry.login == decryptField(obj, "login", key));
+  if (entryExists) return log.warn("Entry exists!");
+
+  SECRET_FIELDS.forEach((f) => (entry[f] = entry[f] && encrypt(entry[f], key)));
+  entry.password = encrypt(await askPassword("Add password:"), key);
+  entry.id = nextEntryId(db.accounts);
+  entry.created = new Date().toISOString();
+  entry.updated = entry.created;
+  db.accounts.push(entry); // push new entry
+  saveOrReport(dbPath, db, "Added entry #" + entry.id, "Error while adding entry!", "added");
+}
+
+module.exports = addEntry;

package/options/check.js

@@ -0,0 +1,123 @@
+const fs = require("fs");
+const { decrypt, isEncrypted, hasMaster, entryLabel, parseDb, dbPath, log, FIELDS, SECRET_FIELDS } = require("../utils");
+
+const ENCRYPTED = ["password", ...SECRET_FIELDS];
+
+// one entry -> list of problems ([] = healthy). Without `key` only the structure is checked (no decryption).
+function checkEntry(entry, key) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return ["not an account object"];
+  const problems = [];
+  if (!Number.isInteger(entry.id) || entry.id < 1) problems.push("bad id (" + JSON.stringify(entry.id) + ")");
+  if (typeof entry.name !== "string" || !entry.name.trim()) problems.push("name is empty");
+  for (const f of FIELDS) if (entry[f] != null && typeof entry[f] !== "string") problems.push(f + " isn't text");
+  if (!entry.password) problems.push("password is empty");
+
+  for (const f of ENCRYPTED) {
+    if (!entry[f] || typeof entry[f] !== "string") continue;
+    if (!isEncrypted(entry[f])) problems.push(f + " isn't encrypted (unknown format)");
+    else if (key && !canDecrypt(entry[f], key)) problems.push(f + " can't be decrypted (damaged)");
+  }
+  for (const f of ["created", "updated"]) if (entry[f] && isNaN(Date.parse(entry[f]))) problems.push(f + " isn't a valid date");
+  return problems;
+}
+
+function canDecrypt(value, key) {
+  try {
+    decrypt(value, key);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+// whole db -> [{ entry, problems }] for the damaged entries only (also catches duplicate ids)
+function checkEntries(db, key) {
+  const seen = new Map(); // id -> count
+  db.forEach((e) => e && e.id != null && seen.set(e.id, (seen.get(e.id) || 0) + 1));
+  return db
+    .map((entry) => {
+      const problems = checkEntry(entry, key);
+      if (entry && seen.get(entry.id) > 1) problems.push("duplicate id (" + seen.get(entry.id) + " entries use #" + entry.id + ")");
+      return { entry, problems };
+    })
+    .filter((r) => r.problems.length);
+}
+
+// a locked vault key { salt, n, key } (credentials.json or db.json "recovery") -> list of problems, prefixed with `label`
+function checkLock(lock, label) {
+  const problems = [];
+  if (typeof lock.salt !== "string" || !/^[0-9a-f]{32}$/.test(lock.salt)) problems.push(label + ": bad salt");
+  if (!Number.isInteger(lock.n) || lock.n < 2 || (lock.n & (lock.n - 1)) !== 0) problems.push(label + ": bad n (must be a power of 2)");
+  if (!isEncrypted(lock.key)) problems.push(label + ": key isn't encrypted (unknown format)");
+  return problems;
+}
+
+// credentials.json -> list of problems. `accounts` tells whether a missing master password is a problem.
+function checkCredentials(cred, accounts) {
+  if (!hasMaster(cred)) {
+    const hasSecrets = accounts.some((e) => e && ENCRYPTED.some((f) => isEncrypted(e[f])));
+    return hasSecrets ? ["credentials.json has no master password, but db.json has encrypted entries (run 'recover' with your recovery phrase, or restore credentials.json.bak)"] : [];
+  }
+  return checkLock(cred, "credentials.json");
+}
+
+// db.json "recovery" -> list of problems (none when there's no recovery phrase)
+function checkRecovery(recovery) {
+  if (recovery == null) return [];
+  if (typeof recovery !== "object" || Array.isArray(recovery)) return ["db.json: recovery isn't an object"];
+  return checkLock(recovery, "db.json recovery");
+}
+
+// accounts of db.json.bak, or null
+function loadBackup(file = dbPath + ".bak") {
+  try {
+    return parseDb(JSON.parse(fs.readFileSync(file, "utf8"))).accounts;
+  } catch (err) {
+    return null;
+  }
+}
+
+// id of a damaged entry -> true when db.json.bak has a healthy copy of it
+function healthyInBackup(entry, backup, key) {
+  if (!backup || !entry || entry.id == null) return false;
+  const copies = backup.filter((e) => e && e.id === entry.id);
+  return copies.length === 1 && checkEntry(copies[0], key).length === 0;
+}
+
+// read-only: print every damaged entry + credentials/recovery problem. askKey() -> vault key, or null (wrong password)
+async function checkDb(db, cred, askKey) {
+  const { accounts } = db;
+  const credProblems = checkCredentials(cred, accounts);
+  const recoveryProblems = checkRecovery(db.recovery);
+  [...credProblems, ...recoveryProblems].forEach((p) => log.problem(p));
+  if (db.recovery == null && accounts.length) log.hint("No recovery phrase yet, create one with 'recovery'");
+
+  let key = null;
+  if (hasMaster(cred) && !credProblems.length) {
+    key = await askKey();
+    if (!key) return void (process.exitCode = 1);
+  } else {
+    log.warn("Can't unlock the vault, checking structure only (no decryption)");
+  }
+
+  const damaged = checkEntries(accounts, key);
+  const backup = damaged.length ? loadBackup() : null;
+  for (const { entry, problems } of damaged) {
+    const label = entry && typeof entry === "object" ? entryLabel(entry) : JSON.stringify(entry);
+    log.problem(label + ": " + problems.join(", "));
+    if (key && healthyInBackup(entry, backup, key)) log.hint("    a healthy copy is in db.json.bak");
+  }
+
+  const total = accounts.length + " entr" + (accounts.length === 1 ? "y" : "ies") + " checked";
+  if (!damaged.length && !credProblems.length && !recoveryProblems.length) return log.ok(total + ", no damage found" + (key ? "" : " (structure only)"));
+  process.exitCode = 1;
+  const notes = (credProblems.length ? ", credentials.json damaged" : "") + (recoveryProblems.length ? ", recovery damaged (make a new one with 'recovery')" : "");
+  log.warn(total + ", " + damaged.length + " damaged" + notes);
+  log.hint("Fix with 'get --id <id> --edit' / '--rm', or restore from db.json.bak / credentials.json.bak");
+}
+
+module.exports = checkDb;
+module.exports.checkEntry = checkEntry;
+module.exports.checkEntries = checkEntries;
+module.exports.checkCredentials = checkCredentials;
+module.exports.checkRecovery = checkRecovery;

package/options/delete.js

@@ -0,0 +1,10 @@
+const { confirm, saveOrReport, entryLabel, dbPath, colors } = require("../utils");
+
+async function deleteEntry(entry, db) {
+  const label = entryLabel(entry);
+  if (!(await confirm("Entry " + label + " will be " + colors.red("deleted") + ", Are you sure"))) return;
+  db.accounts.splice(db.accounts.findIndex((obj) => obj.id == entry.id), 1);
+  saveOrReport(dbPath, db, "Deleted entry " + label, "Error while deleting entry!", "removed");
+}
+
+module.exports = deleteEntry;

package/options/export.js

@@ -0,0 +1,54 @@
+const fs = require("fs");
+const path = require("path");
+const { confirm, decryptField, filterEntries, colors, log, FIELDS, SECRET_FIELDS } = require("../utils");
+const { toCsv } = require("../utils/csv");
+
+const COLUMNS = ["id", ...FIELDS, "password", "created", "updated"];
+
+// entries -> csv text with every secret decrypted, or null if any field couldn't be decrypted (error already printed)
+function entriesToCsv(entries, key) {
+  const rows = [COLUMNS];
+  for (const entry of entries) {
+    const row = [];
+    for (const col of COLUMNS) {
+      const value = col === "password" || SECRET_FIELDS.includes(col) ? decryptField(entry, col, key) : entry[col];
+      if (value === null) return null;
+      row.push(value);
+    }
+    rows.push(row);
+  }
+  return toCsv(rows);
+}
+
+// ask before overwriting `file` -> true when it's ok to write
+async function canWrite(file) {
+  if (!fs.existsSync(file)) return true;
+  return confirm(file + " exists, " + colors.amber("overwrite") + " it");
+}
+
+// write the decrypted entries (all, or the ones matching `query`) to `file`, readable by the owner only
+async function exportEntries(db, query, file, askKey) {
+  const entries = Object.keys(query).length ? filterEntries(db.accounts, query) : db.accounts;
+  if (!entries.length) return log.warn("No entries to export");
+
+  file = path.resolve(file);
+  if (!(await canWrite(file))) return;
+
+  const key = await askKey();
+  if (!key) return;
+  const csv = entriesToCsv(entries, key);
+  if (csv === null) return log.error("Export aborted, nothing written");
+
+  try {
+    fs.writeFileSync(file, csv, { mode: 0o600 });
+    fs.chmodSync(file, 0o600); // mode only applies to new files
+  } catch (err) {
+    process.exitCode = 1;
+    return log.error("Error while exporting!", err);
+  }
+  log.added("Exported " + entries.length + " entr" + (entries.length === 1 ? "y" : "ies") + " to " + file);
+  log.warn("This file is NOT encrypted, delete it when you're done with it.");
+}
+
+module.exports = exportEntries;
+module.exports.entriesToCsv = entriesToCsv;

package/options/get.js

@@ -0,0 +1,16 @@
+const { copyEntry, showEntry, drawTable, filterEntries, log } = require("../utils");
+
+async function getEntry(db, query, opts, key) {
+  const { deleteEntry, updateEntry } = require("./index"); // here, not at the top: options/index.js loads this file, so its exports are only ready at call time
+  if (!Object.keys(query).length) return drawTable(db.accounts); // show all table
+
+  const filteredEntries = filterEntries(db.accounts, query);
+  drawTable(filteredEntries); // show matched items
+
+  const action = opts.edit ? updateEntry : opts.rm ? deleteEntry : opts.cp ? copyEntry : opts.show ? showEntry : null;
+  if (!action || !filteredEntries.length) return;
+  if (filteredEntries.length > 1) return log.warn("Multiple entries matched, narrow it down (e.g. --id <id>)");
+  await action(filteredEntries[0], db, key);
+}
+
+module.exports = getEntry;