keebox 0.0.0-stage → 0.9.0

package/utils/index.js

@@ -0,0 +1,295 @@
+function isAndroid() {
+  return require("os").platform() === "android";
+}
+
+const colors = require("./colors");
+const log = require("./log");
+const { FIELDS, SECRET_FIELDS } = require("./fields");
+const crypto = require("crypto");
+const path = require("path");
+const { once } = require("events");
+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");
+
+// cryptographically secure, exact length, at least one char of each class (length >= 4)
+function mkPass(length) {
+  const sets = ["abcdefghijklmnopqrstuvwxyz", "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "0123456789", "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"];
+  const all = sets.join("");
+  const pick = (str) => str[crypto.randomInt(str.length)];
+  const chars = sets.map(pick);
+  while (chars.length < length) chars.push(pick(all));
+  // Fisher-Yates shuffle
+  for (let i = chars.length - 1; i > 0; i--) {
+    const j = crypto.randomInt(i + 1);
+    [chars[i], chars[j]] = [chars[j], chars[i]];
+  }
+  return chars.join("");
+}
+
+// AES-256-GCM with the vault key -> "iv.tag.data" (no key stored)
+function encrypt(text, key) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const data = Buffer.concat([cipher.update(text, "utf8"), cipher.final()]);
+  return [iv.toString("hex"), cipher.getAuthTag().toString("hex"), data.toString("hex")].join(".");
+}
+
+function decrypt(str, key) {
+  if (!isEncrypted(str)) throw new Error("unknown encryption format");
+  const [iv, tag, data] = str.split(".");
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(iv, "hex"), { authTagLength: 16 });
+  decipher.setAuthTag(Buffer.from(tag, "hex"));
+  return Buffer.concat([decipher.update(Buffer.from(data, "hex")), decipher.final()]).toString("utf8");
+}
+
+// made by encrypt() ("iv.tag.data")
+function isEncrypted(value) {
+  return /^[0-9a-f]{24}\.[0-9a-f]{32}\.[0-9a-f]*$/.test(String(value));
+}
+
+// decrypt one secret field of an entry -> text ("" if empty), or null after printing the error
+function decryptField(entry, field, key) {
+  if (!entry[field]) return "";
+  try {
+    return decrypt(entry[field], key);
+  } catch (err) {
+    log.error("Couldn't decrypt " + field + " of entry #" + entry.id + " (damaged)");
+    process.exitCode = 1;
+    return null;
+  }
+}
+
+// safe write: temp file + fsync + rename (atomic), keeps previous version as <file>.bak
+function saveJson(file, data) {
+  const fs = require("fs");
+  const tmp = file + ".tmp";
+  const fd = fs.openSync(tmp, "w");
+  try {
+    fs.writeFileSync(fd, JSON.stringify(data, null, 2));
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  if (fs.existsSync(file)) fs.copyFileSync(file, file + ".bak");
+  fs.renameSync(tmp, file);
+}
+
+// read json file, create it with `fallback` if missing
+function loadJson(file, fallback) {
+  const fs = require("fs");
+  if (!fs.existsSync(file)) {
+    saveJson(file, fallback);
+    log.hint("Created " + file);
+  }
+  return JSON.parse(fs.readFileSync(file).toString());
+}
+
+// clipboard commands for this OS: [command, args, stdin encoding]
+function clipboardCommands() {
+  const env = process.env;
+  if (process.platform === "darwin") return { copy: ["pbcopy", []], paste: ["pbpaste", []] };
+  if (process.platform === "win32" || env.WSL_DISTRO_NAME) {
+    const exe = process.platform === "win32" ? "" : ".exe"; // WSL calls the Windows binaries
+    return { copy: ["clip" + exe, [], "utf16le"], paste: ["powershell" + exe, ["-NoProfile", "-Command", "Get-Clipboard"]] };
+  }
+  if (env.WAYLAND_DISPLAY) return { copy: ["wl-copy", []], paste: ["wl-paste", ["--no-newline"]], clear: ["wl-copy", ["--clear"]] };
+  return { copy: ["xclip", ["-selection", "clipboard"]], paste: ["xclip", ["-selection", "clipboard", "-o"]] };
+}
+
+// runs in a detached node process (serialized with .toString()), so it must be self-contained
+async function clearClipboardLater(cmds, ms) {
+  const cp = require("child_process");
+  let text = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) text += chunk;
+  await require("timers/promises").setTimeout(ms);
+  const opts = { windowsHide: true, timeout: 5000 };
+  const cur = cp.spawnSync(cmds.paste[0], cmds.paste[1], { ...opts, encoding: "utf8" });
+  if (cur.status !== 0 || ![text, text + "\n", text + "\r\n"].includes(cur.stdout)) return; // changed since, leave it
+  const clear = cmds.clear || cmds.copy;
+  cp.spawnSync(clear[0], clear[1], { ...opts, input: "", stdio: ["pipe", "ignore", "ignore"] });
+}
+
+// copy to clipboard, then clear it after `seconds` (only if it still holds the same text)
+// -> seconds until it clears (0 = couldn't schedule clearing), throws if copying failed
+async function copyToClipboard(text, seconds = 20) {
+  const { spawn } = require("child_process");
+  const cmds = clipboardCommands();
+  const [command, args, encoding] = cmds.copy;
+
+  const child = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"], windowsHide: true });
+  child.on("error", () => {}); // reported through once() below
+  child.stdin.on("error", () => {});
+  child.stdin.end(Buffer.from(String(text), encoding || "utf8"));
+  // xclip/wl-copy stay in the background to serve the clipboard, so wait for "exit" (not stdio "close")
+  const [code] = await once(child, "exit"); // rejects on "error", e.g. ENOENT: command not installed
+  if (code) throw new Error(command + " exited with code " + code);
+
+  try {
+    const script = "(" + clearClipboardLater.toString() + ")(" + JSON.stringify(cmds) + "," + seconds * 1000 + ");";
+    const clearer = spawn(process.execPath, ["-e", script], { detached: true, stdio: ["pipe", "ignore", "ignore"], windowsHide: true });
+    clearer.on("error", () => {});
+    clearer.unref();
+    clearer.stdin.end(String(text)); // password goes via stdin, not argv
+    await once(clearer.stdin, "finish");
+    return seconds;
+  } catch (err) {
+    return 0; // copied, but couldn't schedule clearing
+  }
+}
+
+// ---- shared app helpers ----
+
+// db.json content -> the same { recovery, accounts } object, or throws when it has another shape
+function parseDb(raw) {
+  const ok = raw && typeof raw === "object" && !Array.isArray(raw) && "recovery" in raw && (raw.recovery === null || typeof raw.recovery === "object") && Array.isArray(raw.accounts);
+  if (!ok) throw new Error('db.json must be { "recovery": null | { salt, n, key }, "accounts": [...] }');
+  return raw;
+}
+
+// load db.json + credentials.json (created if missing) -> { db, cred }, or null after printing the error
+// db = { recovery, accounts }: saving `db` writes the whole db.json
+function loadData() {
+  try {
+    const db = parseDb(loadJson(dbPath, { recovery: null, accounts: [] }));
+    const cred = loadJson(credPath, {});
+    if (!cred || typeof cred !== "object" || Array.isArray(cred)) throw new Error("credentials.json must be an object");
+    return { db, cred };
+  } catch (err) {
+    log.error("Couldn't connect to db! (backups: db.json.bak, credentials.json.bak)", "\n", err);
+    return null;
+  }
+}
+
+// save, then print `okMsg` with log[kind] ("added", "updated", "removed", "ok") -> true, or print `errMsg` + the error -> false
+function saveOrReport(file, data, okMsg, errMsg, kind = "added") {
+  try {
+    saveJson(file, data);
+  } catch (err) {
+    log.error(errMsg, err);
+    process.exitCode = 1;
+    return false;
+  }
+  log[kind](okMsg);
+  return true;
+}
+
+// single hidden password prompt -> password
+async function askPassword(message) {
+  return (await prompt([{ type: "password", name: "password", message }])).password;
+}
+
+// yes/no prompt -> true/false
+async function confirm(message) {
+  return (await prompt([{ type: "confirm", name: "ok", message }])).ok;
+}
+
+// run an async entry point: unexpected errors are printed and exit with code 1
+function run(main) {
+  main().catch((err) => {
+    log.error("Unexpected error:", err);
+    process.exitCode = 1;
+  });
+}
+
+// "#3 github (eissa)"
+function entryLabel(entry) {
+  return "#" + entry.id + " " + entry.name + " (" + entry.username + ")";
+}
+
+// copy to the clipboard (auto-cleared), or print it on Android / when copying fails
+// what: shown in "Copied <what> to clipboard" (omitted when empty), show: also print the text on success
+//   show:  "Copied to clipboard (clears in 20s): <text>"   (text in amber)
+//   else:  "✓ Copied password of entry #3 to clipboard, clears in 20s"
+async function copyOrPrint(text, what, show) {
+  if (isAndroid()) return console.log(colors.amber(text));
+  let seconds;
+  try {
+    seconds = await copyToClipboard(text);
+  } catch (err) {
+    log.warnErr("Couldn't copy to clipboard (linux needs xclip, or wl-clipboard on Wayland): " + err.message);
+    return console.log(colors.amber(text));
+  }
+  const copied = "Copied " + (what ? what + " " : "") + "to clipboard";
+  if (show) return console.log(colors.green(copied + (seconds ? " (clears in " + seconds + "s)" : "") + ":") + " " + colors.amber(text));
+  log.ok(copied + (seconds ? ", clears in " + seconds + "s" : ""));
+}
+
+// decrypt an entry's password and copy it (or print it, see copyOrPrint)
+async function copyEntry(entry, db, key) {
+  let password;
+  try {
+    password = decrypt(entry.password, key);
+  } catch (err) {
+    log.error("Couldn't decrypt password of entry #" + entry.id + " (empty or damaged)");
+    process.exitCode = 1;
+    return;
+  }
+  await copyOrPrint(password, "password of entry #" + entry.id);
+}
+
+// print an entry's secret fields (not the password)
+async function showEntry(entry, db, key) {
+  for (const f of SECRET_FIELDS) {
+    const value = decryptField(entry, f, key);
+    if (value === null) return;
+    log.field(f, value);
+  }
+}
+
+// next free entry id: highest id + 1 (1 for an empty db)
+function nextEntryId(entries) {
+  return entries.reduce((max, obj) => Math.max(max, Number(obj.id) || 0), 0) + 1;
+}
+
+// id: exact match, other fields: case-insensitive "contains"
+function filterEntries(entries, query) {
+  const keys = Object.keys(query);
+  return entries.filter((obj) =>
+    keys.every((key) => {
+      if (key === "id") return String(obj.id) === String(query.id).trim();
+      return String(obj[key] ?? "")
+        .toLowerCase()
+        .includes(String(query[key]).toLowerCase());
+    })
+  );
+}
+
+module.exports = {
+  dbPath,
+  credPath,
+  FIELDS,
+  parseDb,
+  SECRET_FIELDS,
+  loadData,
+  saveOrReport,
+  askPassword,
+  confirm,
+  run,
+  entryLabel,
+  copyOrPrint,
+  copyEntry,
+  showEntry,
+  decryptField,
+  nextEntryId,
+  filterEntries,
+  drawTable,
+  prompt,
+  mkPass,
+  decrypt,
+  encrypt,
+  isEncrypted,
+  colors,
+  log,
+  parseArgs,
+  ...require("./mnemonic"),
+};
+
+// vault.js and config.js import from this file at their top, so they load only after module.exports is filled in
+// (earlier they'd get an empty object). One per line: config.js needs vault's functions here already.
+Object.assign(module.exports, require("./vault"));
+Object.assign(module.exports, require("./config"));

package/utils/log.js

@@ -0,0 +1,30 @@
+// one look for every message the CLI prints (same as the website terminal):
+//   ✓ done            green   (log.ok)
+//   [+] Added ...     green   (log.added)       [+] Updated ...  amber (log.updated)
+//   [-] Deleted ...   amber   (log.removed)     [!] damaged ...  red   (log.problem)
+//   ! careful ...     amber   (log.warn)        ✗ failed ...     red   (log.error, stderr)
+//   dim hints         gray    (log.hint)        plain text             (log.info)
+// console.log / console.error are looked up on every call, so tests can swap them.
+const colors = require("./colors");
+
+const out =
+  (prefix, color, stream = "log") =>
+  (msg, ...extra) =>
+    console[stream](color((prefix ? prefix + " " : "") + msg), ...extra);
+
+const log = {
+  info: out("", colors.text),
+  hint: out("", colors.gray),
+  ok: out("✓", colors.green),
+  added: out("[+]", colors.green),
+  updated: out("[+]", colors.amber),
+  removed: out("[-]", colors.amber),
+  warn: out("!", colors.amber),
+  warnErr: out("!", colors.amber, "error"),
+  problem: out("[!]", colors.red, "error"),
+  error: out("✗", colors.red, "error"),
+  // "label: value" pair, e.g. the decrypted notes of an entry
+  field: (label, value) => console.log(colors.amber(label + ":") + " " + (value ? colors.text(value) : colors.dim("-"))),
+};
+
+module.exports = log;

package/utils/mnemonic.js

@@ -0,0 +1,49 @@
+// 12-word recovery phrase, BIP39 style: 128 random bits + 4-bit checksum (first bits of sha256), 11 bits per word
+const crypto = require("crypto");
+const WORDS = require("./wordlist");
+
+const INDEX = new Map(WORDS.map((w, i) => [w, i]));
+const WORD_COUNT = 12;
+const ENTROPY_BYTES = 16; // 128 bits -> 4 checksum bits -> 132 bits = 12 words
+
+const bits = (buf) => [...buf].map((b) => b.toString(2).padStart(8, "0")).join("");
+const checksum = (entropy) => bits(crypto.createHash("sha256").update(entropy).digest()).slice(0, (entropy.length * 8) / 32);
+
+// 16 bytes -> 12 words
+function toWords(entropy) {
+  if (entropy.length !== ENTROPY_BYTES) throw new Error("entropy must be " + ENTROPY_BYTES + " bytes");
+  return (bits(entropy) + checksum(entropy)).match(/.{11}/g).map((b) => WORDS[parseInt(b, 2)]);
+}
+
+// a new random phrase -> "word1 word2 ... word12"
+function newPhrase() {
+  return toWords(crypto.randomBytes(ENTROPY_BYTES)).join(" ");
+}
+
+// typed phrase -> words (lowercase, any spacing)
+function splitPhrase(phrase) {
+  return String(phrase ?? "")
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+// typed phrase -> what's wrong with it, or null when it's a valid 12-word phrase (catches most typos / swapped words)
+function checkPhrase(phrase) {
+  const words = splitPhrase(phrase);
+  if (words.length !== WORD_COUNT) return "needs " + WORD_COUNT + " words, got " + words.length;
+  const unknown = words.filter((w) => !INDEX.has(w));
+  if (unknown.length) return "unknown word(s): " + unknown.join(", ");
+  const all = words.map((w) => INDEX.get(w).toString(2).padStart(11, "0")).join("");
+  const entropy = Buffer.from(all.slice(0, ENTROPY_BYTES * 8).match(/.{8}/g).map((b) => parseInt(b, 2)));
+  if (all.slice(ENTROPY_BYTES * 8) !== checksum(entropy)) return "checksum doesn't match (a word is wrong or out of order)";
+  return null;
+}
+
+// typed phrase -> the exact text used as the scrypt password (so spacing/case don't matter)
+function normalizePhrase(phrase) {
+  return splitPhrase(phrase).join(" ");
+}
+
+module.exports = { toWords, newPhrase, splitPhrase, checkPhrase, normalizePhrase };

package/utils/prompt.js

@@ -0,0 +1,119 @@
+// 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
+// - 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)
+function promptOut() {
+  return process.stdout.isTTY || !process.stderr.isTTY ? process.stdout : process.stderr;
+}
+
+function abortPrompt(code) {
+  if (process.stdin.isTTY && process.stdin.isRaw) process.stdin.setRawMode(false);
+  promptOut().write("\n");
+  process.exit(code);
+}
+
+// interactive text line, with normal editing (arrows, Home/End, ...)
+async function readTtyLine(label) {
+  const rl = readlinePromises.createInterface({ input: process.stdin, output: promptOut(), historySize: 0 });
+  let answered = false;
+  rl.on("SIGINT", () => abortPrompt(130));
+  rl.on("close", () => answered || abortPrompt(1)); // Ctrl+D
+  const answer = await rl.question(label);
+  answered = true;
+  rl.close();
+  return answer;
+}
+
+// interactive password: raw mode, each char shown as a dim "•" (never the text itself); Backspace and Ctrl+U work, pasting works
+const MASK_ERASE = "\b \b";
+function mask(n) {
+  const { colors } = require("./index");
+  return colors.dim("•".repeat(n));
+}
+function readTtyPassword(label) {
+  return new Promise((resolve) => {
+    const { stdin } = process;
+    const out = promptOut();
+    out.write(label);
+    readline.emitKeypressEvents(stdin);
+    stdin.setRawMode(true);
+    stdin.resume();
+    let value = "";
+    const onKey = (str, key = {}) => {
+      if (key.ctrl && key.name === "c") return abortPrompt(130);
+      if (key.ctrl && key.name === "d") return value ? undefined : abortPrompt(1);
+      if (key.name === "return" || key.name === "enter") {
+        stdin.removeListener("keypress", onKey);
+        stdin.setRawMode(false);
+        stdin.pause();
+        out.write("\n");
+        return resolve(value);
+      }
+      const chars = Array.from(value);
+      if (key.name === "backspace") {
+        if (chars.length) out.write(MASK_ERASE);
+        value = chars.slice(0, -1).join(""); // whole char, not half an emoji
+      } else if (key.ctrl && key.name === "u") {
+        out.write(MASK_ERASE.repeat(chars.length));
+        value = "";
+      } else if (str && !key.ctrl && !key.meta && !/[\x00-\x1f\x7f]/.test(str)) {
+        value += str; // skip arrows, tab, etc.
+        out.write(mask(Array.from(str).length));
+      }
+    };
+    stdin.on("keypress", onKey);
+  });
+}
+
+// piped stdin: keep one reader so lines that arrive early are queued, not lost
+let piped;
+function readPipedLine(label) {
+  if (!piped) {
+    piped = { lines: [], waiting: null, closed: false };
+    piped.rl = readline.createInterface({ input: process.stdin, terminal: false, crlfDelay: Infinity }); // \r\n = one line (Windows)
+    piped.rl.on("line", (line) => (piped.waiting ? piped.waiting(line) : piped.lines.push(line)));
+    piped.rl.on("close", () => ((piped.closed = true), piped.waiting && abortPrompt(1)));
+  }
+  promptOut().write(label);
+  return new Promise((resolve) => {
+    const done = (line) => {
+      piped.waiting = null;
+      piped.rl.pause(); // lets the process exit when no more questions come
+      promptOut().write("\n"); // piped answers aren't echoed
+      resolve(line);
+    };
+    if (piped.lines.length) return done(piped.lines.shift());
+    if (piped.closed) return abortPrompt(1);
+    piped.waiting = done;
+    piped.rl.resume();
+  });
+}
+
+async function prompt(questions) {
+  const { colors: c } = require("./index"); // here, not at the top: index.js loads this file, so its exports are only ready at call time
+  const tty = Boolean(process.stdin.isTTY);
+  const read = (label, type) => (!tty ? readPipedLine(label) : type === "password" ? readTtyPassword(label) : readTtyLine(label));
+  const answers = {};
+  for (const q of questions) {
+    // website look: "? MASTER PASSWORD: ••••••" with a gray "?", off-white question and dim hints
+    const hint = q.type === "confirm" ? c.dim(q.default === false ? " (y/N)" : " (Y/n)") : "";
+    const label = c.gray("? ") + c.text(String(q.message).trim()) + hint + " ";
+    // Git Bash/mintty without winpty: no terminal, so the terminal itself echoes what you type
+    if (q.type === "password" && !tty && process.env.MSYSTEM && !process.stdout.isTTY)
+      process.stderr.write(c.yellow("warning: input will be visible, run with: winpty node ...\n"));
+    let answer = await read(label, q.type);
+    if (q.type === "confirm") {
+      while (!/^(y(es)?|no?|)$/i.test(answer.trim())) answer = await read(label, q.type); // re-ask on junk
+      answer = answer.trim() === "" ? q.default !== false : /^y/i.test(answer.trim());
+    } else if (answer === "" && q.default !== undefined) answer = q.default;
+    answers[q.name] = answer;
+  }
+  return answers;
+}
+
+module.exports = prompt;

package/utils/table.js

@@ -0,0 +1,69 @@
+// entries table: drawTable(entries) prints a box table (no passwords), fitted to the terminal width
+const textWidth = (str) => [...str].length;
+const cleanCell = (val) =>
+  String(val ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+const truncate = (str, max) => (textWidth(str) <= max ? str : [...str].slice(0, Math.max(max - 1, 0)).join("") + "…");
+const pad = (str, w, right) => (right ? " ".repeat(w - textWidth(str)) + str : str + " ".repeat(w - textWidth(str)));
+
+// "15-11-2026" (day-month-year) in local time, "" if missing/invalid (entries added before timestamps existed)
+const formatDate = (iso) => {
+  const d = new Date(iso);
+  if (!iso || isNaN(d)) return "";
+  return String(d.getDate()).padStart(2, "0") + "-" + String(d.getMonth() + 1).padStart(2, "0") + "-" + d.getFullYear();
+};
+const DATE_COLUMNS = ["created", "updated"];
+
+// shrink the widest columns until the table fits the terminal (columns in `fixed` never shrink)
+function fitWidths(widths, maxTotal, fixed) {
+  const total = () => widths.reduce((a, b) => a + b, 0) + widths.length * 3 + 1; // "│ " + " " per cell + last "│"
+  while (total() > maxTotal) {
+    let widest = -1;
+    for (let i = 0; i < widths.length; i++) if (!fixed.includes(i) && (widest === -1 || widths[i] > widths[widest])) widest = i;
+    if (widest === -1 || widths[widest] <= 4) break; // can't shrink any further, let the terminal wrap
+    widths[widest]--;
+  }
+  return widths;
+}
+
+// print entries as a box table (no passwords)
+function drawTable(entries) {
+  const { FIELDS, SECRET_FIELDS, colors } = require("./index"); // here, not at the top: index.js loads this file, so its exports are only ready at call time
+  const COLUMNS = ["id", ...FIELDS, ...DATE_COLUMNS];
+  if (!entries.length) return console.log(colors.gray("0 entries"));
+
+  const cell = (obj, col) => {
+    if (SECRET_FIELDS.includes(col) && obj[col]) return "***";
+    if (col === "updated" && formatDate(obj.updated) === formatDate(obj.created)) return ""; // same day as created -> "-"
+    return DATE_COLUMNS.includes(col) ? formatDate(obj[col]) : cleanCell(obj[col]);
+  };
+  const rows = entries.map((obj) => COLUMNS.map((col) => cell(obj, col)));
+  const widths = COLUMNS.map((col, i) => Math.max(col.length, ...rows.map((r) => textWidth(r[i]) || 1)));
+  const fixed = COLUMNS.map((col, i) => (col === "id" || DATE_COLUMNS.includes(col) ? i : -1)).filter((i) => i !== -1);
+  fitWidths(widths, process.stdout.columns || Infinity, fixed);
+
+  // website look: dim rounded frame, amber bold headers, amber ids, off-white values, dim "-" for empty cells
+  const line = (l, m, r) => colors.dim(l + widths.map((w) => "─".repeat(w + 2)).join(m) + r);
+  const bar = colors.dim("│");
+  const row = (cells) => bar + cells.map((c) => " " + c + " ").join(bar) + bar;
+
+  const out = [line("╭", "┬", "╮"), row(COLUMNS.map((col, i) => colors.bold.amber(pad(truncate(col.toUpperCase(), widths[i]), widths[i])))), line("├", "┼", "┤")];
+  rows.forEach((r) => {
+    out.push(
+      row(
+        r.map((val, i) => {
+          if (!val) return colors.dim(pad("-", widths[i]));
+          const text = pad(truncate(val, widths[i]), widths[i], i === 0);
+          if (i === 0) return colors.amber(text);
+          return val === "***" ? colors.gray(text) : colors.text(text);
+        })
+      )
+    );
+  });
+  out.push(line("╰", "┴", "╯"));
+  out.push(colors.gray(" " + entries.length + (entries.length === 1 ? " entry" : " entries")));
+  console.log(out.join("\n"));
+}
+
+module.exports = drawTable;

package/utils/vault.js

@@ -0,0 +1,50 @@
+// Vault key handling:
+// - one random 256-bit "vault key" encrypts every entry password (see utils.encrypt)
+// - credentials.json holds that vault key, encrypted with a key derived
+//   from the master password (scrypt + random salt): { salt, n, key }
+// - db.json "recovery" holds the same vault key, locked the same way with a 12-word
+//   recovery phrase instead of the master password, so losing credentials.json
+//   (or forgetting the master password) isn't fatal
+const crypto = require("crypto");
+const { encrypt, decrypt } = require("./index");
+const { newPhrase, normalizePhrase } = require("./mnemonic");
+
+const SCRYPT_N = 32768; // ~100ms on a laptop, slows down brute force
+
+function deriveKey(password, saltHex, n) {
+  return crypto.scryptSync(password, Buffer.from(saltHex, "hex"), 32, { N: n, r: 8, p: 1, maxmem: 64 * 1024 * 1024 });
+}
+
+// master password + vault key -> credentials object { salt, n, key }
+function lockVault(password, vaultKey) {
+  const salt = crypto.randomBytes(16).toString("hex");
+  return { salt, n: SCRYPT_N, key: encrypt(vaultKey.toString("hex"), deriveKey(password, salt, SCRYPT_N)) };
+}
+
+function hasMaster(cred) {
+  return Boolean(cred.key);
+}
+
+// master password -> vault key (or null if wrong / no master yet)
+function unlock(password, cred) {
+  if (!hasMaster(cred)) return null;
+  try {
+    return Buffer.from(decrypt(cred.key, deriveKey(password, cred.salt, cred.n)), "hex");
+  } catch (err) {
+    return null; // wrong password
+  }
+}
+
+// vault key -> { phrase, recovery }: a new 12-word phrase + the vault key locked with it (db.json "recovery")
+function makeRecovery(vaultKey) {
+  const phrase = newPhrase();
+  return { phrase, recovery: lockVault(phrase, vaultKey) };
+}
+
+// recovery phrase + db.json "recovery" -> vault key, or null (wrong phrase / no recovery). Spacing and case don't matter.
+function recover(phrase, recovery) {
+  if (!recovery) return null;
+  return unlock(normalizePhrase(phrase), recovery);
+}
+
+module.exports = { lockVault, hasMaster, unlock, makeRecovery, recover };