keebox 0.0.0-stage → 0.9.0

package/test/recovery.test.js

@@ -0,0 +1,129 @@
+// run: npm test  (or: node --test)
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+const crypto = require("crypto");
+const { encrypt, decrypt, lockVault, unlock, makeRecovery, recover, parseDb, toWords, newPhrase, checkPhrase, normalizePhrase } = require("../utils");
+const { checkRecovery } = require("../options/check");
+const { formatPhrase } = require("../options/recovery");
+const WORDS = require("../utils/wordlist");
+
+describe("wordlist", () => {
+  test("is the BIP39 English list", () => {
+    assert.equal(WORDS.length, 2048);
+    assert.equal(new Set(WORDS).size, 2048);
+    const hash = crypto.createHash("sha256").update(WORDS.join("\n") + "\n").digest("hex");
+    assert.equal(hash, "2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda");
+  });
+});
+
+describe("mnemonic", () => {
+  test("matches the official BIP39 test vectors", () => {
+    const vectors = {
+      "00000000000000000000000000000000": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
+      "7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f": "legal winner thank year wave sausage worth useful legal winner thank yellow",
+      "80808080808080808080808080808080": "letter advice cage absurd amount doctor acoustic avoid letter advice cage above",
+      ffffffffffffffffffffffffffffffff: "zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong",
+    };
+    for (const [hex, phrase] of Object.entries(vectors)) {
+      assert.equal(toWords(Buffer.from(hex, "hex")).join(" "), phrase);
+      assert.equal(checkPhrase(phrase), null);
+    }
+  });
+
+  test("new phrases are 12 valid, random words", () => {
+    const seen = new Set();
+    for (let i = 0; i < 200; i++) {
+      const p = newPhrase();
+      assert.equal(p.split(" ").length, 12);
+      assert.equal(checkPhrase(p), null);
+      seen.add(p);
+    }
+    assert.equal(seen.size, 200);
+  });
+
+  test("accepts any case / spacing", () => {
+    const p = newPhrase();
+    const messy = "  " + p.toUpperCase().split(" ").join(" \n\t ") + " ";
+    assert.equal(checkPhrase(messy), null);
+    assert.equal(normalizePhrase(messy), p);
+  });
+
+  test("reports wrong word count, unknown words, bad checksum", () => {
+    const words = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about".split(" ");
+    assert.match(checkPhrase(words.slice(1).join(" ")), /needs 12 words, got 11/);
+    assert.match(checkPhrase(""), /got 0/);
+    assert.match(checkPhrase([...words.slice(0, 11), "abuot"].join(" ")), /unknown word\(s\): abuot/);
+    assert.match(checkPhrase([...words.slice(0, 11), "abandon"].join(" ")), /checksum/); // valid word, wrong one
+  });
+
+  test("swapping two words is almost always caught", () => {
+    let caught = 0;
+    for (let i = 0; i < 200; i++) {
+      const w = newPhrase().split(" ");
+      if (w[0] === w[1]) continue;
+      [w[0], w[1]] = [w[1], w[0]];
+      if (checkPhrase(w.join(" "))) caught++;
+    }
+    assert.ok(caught > 150, "caught " + caught + "/200"); // 4-bit checksum: ~15/16
+  });
+});
+
+describe("recovery (vault key locked with the phrase)", () => {
+  // scrypt is slow on purpose, so share one recovery
+  const vaultKey = crypto.randomBytes(32);
+  const { phrase, recovery } = makeRecovery(vaultKey);
+  const entry = encrypt("site password", vaultKey);
+
+  test("recovery -> { salt, n, key } without the vault key in it", () => {
+    assert.deepEqual(Object.keys(recovery).sort(), ["key", "n", "salt"]);
+    assert.ok(!JSON.stringify(recovery).includes(vaultKey.toString("hex")));
+    assert.deepEqual(checkRecovery(recovery), []);
+  });
+
+  test("the phrase opens the vault key, even typed messily", () => {
+    assert.ok(recover(phrase, recovery).equals(vaultKey));
+    assert.ok(recover("  " + phrase.toUpperCase().replace(/ /g, "   ") + "\n", recovery).equals(vaultKey));
+  });
+
+  test("wrong phrase / no recovery / tampered recovery -> null", () => {
+    assert.equal(recover(newPhrase(), recovery), null);
+    assert.equal(recover(phrase, null), null);
+    assert.equal(recover(phrase, { ...recovery, key: recovery.key.replace(/.$/, (c) => (c === "0" ? "1" : "0")) }), null);
+  });
+
+  test("lost credentials.json: phrase -> vault key -> new master password, old entries still decrypt", () => {
+    const key = recover(phrase, recovery);
+    const cred = lockVault("brand new master", key); // what 'recover' saves as the new credentials.json
+    assert.equal(decrypt(entry, unlock("brand new master", cred)), "site password");
+    assert.ok(recover(phrase, recovery).equals(unlock("brand new master", cred))); // phrase keeps working
+  });
+
+  test("a new phrase replaces the old one", () => {
+    const next = makeRecovery(vaultKey);
+    assert.notEqual(next.phrase, phrase);
+    assert.equal(recover(phrase, next.recovery), null);
+    assert.ok(recover(next.phrase, next.recovery).equals(vaultKey));
+  });
+
+  test("checkRecovery finds a damaged recovery", () => {
+    assert.deepEqual(checkRecovery(null), []);
+    assert.deepEqual(checkRecovery([]), ["db.json: recovery isn't an object"]);
+    assert.deepEqual(checkRecovery({ salt: "x", n: 3, key: "x" }), ["db.json recovery: bad salt", "db.json recovery: bad n (must be a power of 2)", "db.json recovery: key isn't encrypted (unknown format)"]);
+  });
+
+  test("formatPhrase numbers all 12 words", () => {
+    const plain = formatPhrase(phrase).replace(/\x1b\[[0-9;]*m/g, "");
+    phrase.split(" ").forEach((w, i) => assert.ok(plain.includes(i + 1 + ". " + w), w));
+  });
+});
+
+describe("parseDb", () => {
+  test("accepts { recovery, accounts }", () => {
+    for (const db of [{ recovery: { salt: "s", n: 2, key: "k" }, accounts: [{ id: 1 }] }, { recovery: null, accounts: [] }]) assert.equal(parseDb(db), db);
+  });
+
+  test("rejects anything else, including a plain array of accounts", () => {
+    const bad = [[], [{ id: 1, name: "a" }], null, {}, { accounts: [] }, { recovery: null }, { recovery: null, accounts: {} }, { recovery: "x", accounts: [] }, "x", 1];
+    for (const b of bad) assert.throws(() => parseDb(b), /db.json must be/, JSON.stringify(b));
+  });
+});

package/utils/cli.js

@@ -0,0 +1,130 @@
+// minimal commander replacement
+// supports: --opt <value>, --opt=value, boolean --flag, commands, options before or after the command,
+// -h/--help, help [command], -V/--version, "--" (end of options), help wrapped to the terminal width.
+// errors go to stderr with exit code 1. Uses process.exitCode (not process.exit) so piped output is never cut off.
+const colors = require("./colors");
+
+// spec: { version, description, options: [["--id <id>", "desc"], ["--cp", "desc"]], commands: { add: "desc" } }
+// returns { command, opts, args }, or null when it already handled help/version/an error
+function parseArgs(argv, spec) {
+  const name = "keebox";
+  const builtins = [
+    ["-V, --version", "output the version number"],
+    ["-h, --help", "display help for command"],
+  ];
+  const defs = spec.options.concat(builtins).map(([flags, desc]) => {
+    const m = /^(?:-(\w), )?--([\w-]+)(?: <[\w-]+>)?$/.exec(flags);
+    if (!m) throw new Error("bad option spec: " + flags);
+    return { flags, desc, short: m[1], long: m[2], key: m[2].replace(/-(\w)/g, (_, c) => c.toUpperCase()), takesValue: flags.endsWith(">") };
+  });
+
+  // "✗ error: unknown option '--nme'" in red, then the "(Did you mean --name?)" hint in gray
+  const fail = (msg) => {
+    const [first, ...rest] = msg.split("\n");
+    process.stderr.write(colors.red("✗ error: " + first) + "\n" + rest.map((l) => colors.gray(l.trim()) + "\n").join(""));
+    process.exitCode = 1;
+    return null;
+  };
+
+  const opts = {};
+  const args = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      args.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.length < 2 || arg[0] !== "-") {
+      args.push(arg);
+      continue;
+    }
+    const eq = arg.startsWith("--") ? arg.indexOf("=") : -1;
+    const flag = eq === -1 ? arg : arg.slice(0, eq);
+    const def = defs.find((d) => flag === "--" + d.long || (d.short && flag === "-" + d.short));
+    if (!def) return fail(`unknown option '${arg}'` + suggest(flag, defs.map((d) => "--" + d.long)));
+    if (!def.takesValue) {
+      if (eq !== -1) return fail(`option '${flag}' does not take a value`);
+      opts[def.key] = true;
+      continue;
+    }
+    const value = eq !== -1 ? arg.slice(eq + 1) : argv[++i];
+    if (value === undefined) return fail(`option '${def.flags}' argument missing`);
+    opts[def.key] = value; // repeated option: last one wins
+  }
+
+  const isCommand = (c) => Object.prototype.hasOwnProperty.call(spec.commands, c); // not "constructor", "toString", ...
+  const command = args[0];
+  if (opts.version) return void process.stdout.write(spec.version + "\n");
+  if (opts.help) return void process.stdout.write(help(isCommand(command) ? command : null));
+  if (command === "help") {
+    if (args[1] && !isCommand(args[1])) return fail(`unknown command '${args[1]}'`);
+    return void process.stdout.write(help(args[1]));
+  }
+  if (!command) {
+    process.stderr.write(help());
+    process.exitCode = 1;
+    return null;
+  }
+  if (!isCommand(command)) return fail(`unknown command '${command}'` + suggest(command, Object.keys(spec.commands)) + "\nTry running --help");
+  delete opts.help;
+  delete opts.version;
+  return { command, opts, args: args.slice(1) };
+
+  // website look: amber section titles and "$ keebox ..." usage line, off-white terms, gray descriptions
+  function help(cmd) {
+    const heading = (t) => colors.bold.amber(t);
+    const usage = (args) => colors.amber("$ ") + colors.text(name + " " + args);
+    if (cmd) return `${heading("Usage")}\n  ${usage(cmd + " [options]")}\n\n${colors.gray(spec.commands[cmd])}\n\n${heading("Options")}\n${table([builtins[1]])}\n`;
+    const commands = Object.entries(spec.commands).concat([["help [command]", "display help for command"]]);
+    const options = spec.options.concat(builtins);
+    return `${heading("Usage")}\n  ${usage("[options] [command]")}\n\n${colors.gray(spec.description)}\n\n${heading("Options")}\n${table(options, commands)}\n\n${heading("Commands")}\n${table(commands, options)}\n`;
+  }
+}
+
+// two-column list, descriptions wrapped to the terminal width (columns line up across both lists)
+function table(rows, otherRows = []) {
+  const pad = Math.max(...rows.concat(otherRows).map(([term]) => term.length));
+  const width = Math.max((process.stdout.columns || 80) - pad - 4, 40);
+  // "<value>" / "[command]" placeholders dim, the rest of the term off-white
+  const styleTerm = (term) => term.replace(/([<\[][^>\]]+[>\]])|([^<\[]+)/g, (_, arg, text) => (arg ? colors.dim(arg) : colors.text(text)));
+  return rows.map(([term, desc]) => "  " + styleTerm(term) + " ".repeat(pad - term.length) + "  " + wrap(desc, width).map((l) => colors.gray(l)).join("\n" + " ".repeat(pad + 4))).join("\n");
+}
+
+function wrap(text, width) {
+  const lines = [""];
+  for (const word of text.split(/\s+/)) {
+    const last = lines[lines.length - 1];
+    if (last && last.length + 1 + word.length > width) lines.push(word);
+    else lines[lines.length - 1] = last ? last + " " + word : word;
+  }
+  return lines;
+}
+
+// "(Did you mean --name?)" / "(Did you mean one of ...?)": closest matches within 2 edits (a swap counts as 1)
+function suggest(input, candidates) {
+  const strip = (s) => s.replace(/^--/, "");
+  const dist = (a, b) => {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i]);
+    for (let j = 1; j <= b.length; j++) d[0][j] = j;
+    for (let i = 1; i <= a.length; i++)
+      for (let j = 1; j <= b.length; j++) {
+        d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+      }
+    return d[a.length][b.length];
+  };
+  let best = 3;
+  let similar = [];
+  for (const c of candidates) {
+    const [a, b] = [strip(input), strip(c)];
+    const distance = dist(a, b);
+    const length = Math.max(a.length, b.length);
+    if (b.length <= 1 || (length - distance) / length <= 0.4 || distance > best) continue;
+    if (distance < best) (best = distance), (similar = []);
+    similar.push(c);
+  }
+  similar.sort();
+  return similar.length > 1 ? `\n(Did you mean one of ${similar.join(", ")}?)` : similar.length ? `\n(Did you mean ${similar[0]}?)` : "";
+}
+
+module.exports = parseArgs;

package/utils/colors.js

@@ -0,0 +1,71 @@
+// tiny ANSI color helper (replaces the "colors" package): colors.red("x"), colors.bold.amber("x")
+// KeeBox palette (same as the website): warm amber accent, soft green / red, warm grays on a dark terminal.
+// - truecolor when the terminal says so (COLORTERM=truecolor|24bit, or a known truecolor terminal),
+//   else the closest xterm-256 color, else the basic 16 ANSI colors
+// - disabled when output isn't a terminal or NO_COLOR is set, FORCE_COLOR turns it on (FORCE_COLOR=0 turns it off)
+const env = process.env;
+
+function colorLevel() {
+  if ("NO_COLOR" in env || env.FORCE_COLOR === "0" || env.FORCE_COLOR === "false") return 0;
+  if (!("FORCE_COLOR" in env) && !process.stdout.isTTY) return 0; // "get > list.txt" stays plain text
+  if (env.TERM === "dumb" && !("FORCE_COLOR" in env)) return 0;
+  if (env.FORCE_COLOR === "3" || /^(truecolor|24bit)$/i.test(env.COLORTERM || "")) return 3;
+  if (["iTerm.app", "WezTerm", "vscode", "ghostty"].includes(env.TERM_PROGRAM) || env.WT_SESSION || /kitty|alacritty|direct/.test(env.TERM || "")) return 3;
+  if (process.platform === "win32") return 3; // Windows 10+ console supports 24-bit
+  if (env.FORCE_COLOR === "2" || /256/.test(env.TERM || "")) return 2;
+  return 1;
+}
+const level = colorLevel();
+
+// [hex, basic ANSI fallback]
+const PALETTE = {
+  amber: ["#f5a524", 33], // accent: headers, ids, the "$" prompt
+  green: ["#7ccf8a", 32], // success
+  red: ["#f07a6e", 31], // errors
+  blue: ["#7aa8f0", 34], // info
+  text: ["#ece6da", 37], // regular text, a warm off-white
+  gray: ["#8a847a", 90], // hints, secondary text
+  dim: ["#55514b", 90], // borders, empty cells, comments
+};
+const ALIASES = { yellow: "amber", cyan: "amber", white: "text", muted: "gray" }; // older names keep working
+
+const hexToRgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+// closest xterm-256 color: nearest of the 6x6x6 cube (16-231) and the grayscale ramp (232-255)
+const CUBE = [0, 95, 135, 175, 215, 255];
+function rgbTo256(rgb) {
+  const dist = (c) => c.reduce((sum, v, i) => sum + (v - rgb[i]) ** 2, 0);
+  const near = (v) => CUBE.reduce((best, c, i) => (Math.abs(c - v) < Math.abs(CUBE[best] - v) ? i : best), 0);
+  const [r, g, b] = rgb.map(near);
+  const cube = { code: 16 + 36 * r + 6 * g + b, d: dist([CUBE[r], CUBE[g], CUBE[b]]) };
+  const step = Math.max(0, Math.min(23, Math.round((rgb.reduce((a, v) => a + v, 0) / 3 - 8) / 10)));
+  const gray = { code: 232 + step, d: dist(Array(3).fill(8 + step * 10)) };
+  return gray.d < cube.d ? gray.code : cube.code;
+}
+function fg(hex, basic) {
+  if (level === 3) return [`38;2;${hexToRgb(hex).join(";")}`, 39];
+  if (level === 2) return [`38;5;${rgbTo256(hexToRgb(hex))}`, 39];
+  return [basic, 39];
+}
+
+const STYLES = { bold: [1, 22], italic: [3, 23], underline: [4, 24] };
+for (const name in PALETTE) STYLES[name] = fg(...PALETTE[name]);
+for (const name in ALIASES) STYLES[name] = STYLES[ALIASES[name]];
+
+function style(codes) {
+  // re-open the outer style after a nested reset, so colors.green("a " + colors.bold("b") + " c") stays green
+  const fn = (str) =>
+    level
+      ? codes.reduceRight((s, [open, close]) => `\x1b[${open}m${s.split(`\x1b[${close}m`).join(`\x1b[${close}m\x1b[${open}m`)}\x1b[${close}m`, String(str))
+      : String(str);
+  for (const name in STYLES) Object.defineProperty(fn, name, { get: () => style([...codes, STYLES[name]]) });
+  return fn;
+}
+const colors = style([]);
+
+colors.enabled = level > 0;
+colors.level = level;
+// text without ANSI codes / its width on screen
+colors.strip = (str) => String(str).replace(/\x1b\[[0-9;]*m/g, "");
+colors.width = (str) => [...colors.strip(str)].length;
+
+module.exports = colors;

package/utils/config.js

@@ -0,0 +1,40 @@
+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
+if (require.main === module) run(main);
+module.exports = { createMaster };
+
+async function main() {
+  const data = loadData();
+  if (!data) return;
+  const { db, cred } = data;
+  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");
+    return createMaster(cred, crypto.randomBytes(32)); // first time: new vault key
+  }
+
+  // changing it requires the current one; the vault key stays the same, so db.json is untouched
+  const key = unlock((await askPassword("Current MASTER PASSWORD: ")).trim(), cred);
+  if (!key) return log.error("Wrong password!");
+  await createMaster(cred, key, "New MASTER PASSWORD: ");
+}
+
+// ask for a master password and lock `vaultKey` with it -> vaultKey, or null if nothing was saved
+async function createMaster(cred, vaultKey, message = "Choose a MASTER PASSWORD: ") {
+  const password = (await askPassword(message)).trim();
+  if (!password) return fail("MASTER PASSWORD can't be empty");
+  const retyped = (await askPassword("Re-type: ")).trim();
+  if (password != retyped) return fail("MASTER PASSWORD not matched");
+  const [okMsg, kind] = hasMaster(cred) ? ["Changed MASTER PASSWORD", "updated"] : ["Added MASTER PASSWORD", "added"];
+  const next = lockVault(password, vaultKey);
+  if (!saveOrReport(credPath, next, okMsg, "Error while saving credentials!", kind)) return null;
+  Object.assign(cred, next);
+  return vaultKey;
+
+  function fail(msg) {
+    log.error(msg);
+    return null;
+  }
+}

package/utils/csv.js

@@ -0,0 +1,59 @@
+// RFC 4180 CSV: fields with a comma, quote or line break are quoted ("" for a quote), rows end with CRLF.
+// Values are written as-is (no spreadsheet formula escaping), so passwords like "=abc" or "-x" survive a re-import.
+function csvField(value) {
+  const s = value == null ? "" : String(value);
+  return /[",\r\n]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+}
+
+// rows: array of arrays -> csv text
+function toCsv(rows) {
+  return rows.map((row) => row.map(csvField).join(",")).join("\r\n") + "\r\n";
+}
+
+// csv text -> array of rows (arrays of strings). Accepts CRLF or LF, a leading BOM, quoted fields with
+// "" and line breaks inside; skips blank lines. Throws on an unclosed quote or text right after a closing quote.
+function parseCsv(text) {
+  text = String(text).replace(/^/, "");
+  const rows = [];
+  let row = [];
+  let field = "";
+  let line = 1;
+  let i = 0;
+  const endField = () => (row.push(field), (field = ""));
+  const endRow = () => {
+    endField();
+    if (row.length > 1 || row[0] !== "") rows.push(row); // skip blank lines
+    row = [];
+  };
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '"' && field === "") {
+      const start = line;
+      i++;
+      for (;;) {
+        if (i >= text.length) throw new Error("unclosed quote (line " + start + ")");
+        if (text[i] === '"') {
+          if (text[i + 1] === '"') (field += '"'), (i += 2);
+          else break;
+        } else {
+          if (text[i] === "\n") line++;
+          field += text[i++];
+        }
+      }
+      i++; // closing quote
+      if (i < text.length && !/[,\r\n]/.test(text[i])) throw new Error("unexpected text after closing quote (line " + line + ")");
+      continue;
+    }
+    if (ch === ",") endField();
+    else if (ch === "\r" || ch === "\n") {
+      if (ch === "\r" && text[i + 1] === "\n") i++;
+      endRow();
+      line++;
+    } else field += ch;
+    i++;
+  }
+  if (field !== "" || row.length) endRow();
+  return rows;
+}
+
+module.exports = { toCsv, parseCsv };

package/utils/fields.js

@@ -0,0 +1,6 @@
+// entry fields (besides id/password/created/updated), also the table columns after id
+const FIELDS = ["name", "url", "username", "login", "notes"];
+// fields encrypted like the password: "***" in the table, read with --show
+const SECRET_FIELDS = ["login", "notes"];
+
+module.exports = { FIELDS, SECRET_FIELDS };