keebox 0.0.0-stage → 0.9.1

package/options/import.js

@@ -0,0 +1,90 @@
+const fs = require("fs");
+const path = require("path");
+const { confirm, encrypt, decryptField, saveOrReport, nextEntryId, dbPath, log, FIELDS, SECRET_FIELDS } = require("../utils");
+const { parseCsv } = require("../utils/csv");
+
+const REQUIRED = ["name", "password"];
+
+// csv rows (first = header) -> { records, errors }. Columns are matched by header name (any order, case-insensitive);
+// unknown columns (e.g. "id") are ignored, missing optional ones are empty.
+function rowsToRecords(rows) {
+  if (!rows.length) return { records: [], errors: ["file is empty"] };
+  const header = rows[0].map((h) => h.trim().toLowerCase());
+  const missing = REQUIRED.filter((c) => !header.includes(c));
+  if (missing.length) return { records: [], errors: ["missing column(s): " + missing.join(", ") + " (header: " + rows[0].join(",") + ")"] };
+
+  const records = [];
+  const errors = [];
+  rows.slice(1).forEach((row, i) => {
+    const at = "row " + (i + 1) + ": ";
+    if (row.length !== header.length) return errors.push(at + "has " + row.length + " columns, header has " + header.length);
+    const rec = {};
+    header.forEach((h, j) => (rec[h] = row[j]));
+    rec.name = rec.name.trim();
+    if (!rec.name) return errors.push(at + "name is empty");
+    records.push(rec);
+  });
+  return { records, errors };
+}
+
+// valid date -> ISO string, else null
+function isoDate(value) {
+  const t = Date.parse(value);
+  return value && !isNaN(t) ? new Date(t).toISOString() : null;
+}
+
+// "same account" like `add`: name + url + username + login
+function sameKey(e) {
+  return JSON.stringify(["name", "url", "username", "login"].map((f) => e[f] || ""));
+}
+
+async function importEntries(db, file, askKey) {
+  file = path.resolve(file);
+  let rows;
+  try {
+    rows = parseCsv(fs.readFileSync(file, "utf8"));
+  } catch (err) {
+    process.exitCode = 1;
+    return log.error("Couldn't read " + file + ": " + err.message);
+  }
+  const { records, errors } = rowsToRecords(rows);
+  if (errors.length) {
+    process.exitCode = 1;
+    errors.forEach((e) => log.problem(e));
+    return log.error("Import aborted, nothing changed");
+  }
+  if (!records.length) return log.warn("No entries in " + file);
+
+  const key = await askKey();
+  if (!key) return;
+
+  // accounts already in db (login decrypted), plus the ones added from this file
+  const seen = new Set();
+  for (const e of db.accounts) {
+    const login = decryptField(e, "login", key);
+    if (login === null) return log.error("Import aborted, fix or delete entry #" + e.id + " first");
+    seen.add(sameKey({ ...e, login }));
+  }
+  const fresh = records.filter((r) => !seen.has(sameKey(r)) && seen.add(sameKey(r)));
+  const skipped = records.length - fresh.length;
+
+  const note = skipped ? " (" + skipped + " already in db, skipped)" : "";
+  if (!fresh.length) return log.warn("Nothing to import" + note);
+  if (!(await confirm("Import " + fresh.length + " entr" + (fresh.length === 1 ? "y" : "ies") + note))) return;
+
+  const now = new Date().toISOString();
+  let id = nextEntryId(db.accounts);
+  for (const r of fresh) {
+    const entry = { id: id++ };
+    FIELDS.forEach((f) => (entry[f] = r[f] || ""));
+    SECRET_FIELDS.forEach((f) => (entry[f] = entry[f] && encrypt(entry[f], key)));
+    entry.password = encrypt(r.password, key);
+    entry.created = isoDate(r.created) || now;
+    entry.updated = isoDate(r.updated) || entry.created;
+    db.accounts.push(entry);
+  }
+  saveOrReport(dbPath, db, "Imported " + fresh.length + " entr" + (fresh.length === 1 ? "y" : "ies") + note, "Error while importing!", "added");
+}
+
+module.exports = importEntries;
+module.exports.rowsToRecords = rowsToRecords;

package/options/index.js

@@ -0,0 +1,20 @@
+const addEntry = require("./add");
+const getEntry = require("./get");
+const updateEntry = require("./update");
+const deleteEntry = require("./delete");
+const exportEntries = require("./export");
+const importEntries = require("./import");
+const checkDb = require("./check");
+const { createRecovery, recoverVault } = require("./recovery");
+
+module.exports = {
+  addEntry,
+  getEntry,
+  updateEntry,
+  deleteEntry,
+  exportEntries,
+  importEntries,
+  checkDb,
+  createRecovery,
+  recoverVault,
+};

package/options/recovery.js

@@ -0,0 +1,63 @@
+const { askPassword, confirm, prompt, saveOrReport, dbPath, colors, log, makeRecovery, recover, checkPhrase, normalizePhrase, createMaster } = require("../utils");
+
+// create (or replace) the 12-word recovery phrase: locks the vault key with it into db.json, shows it once
+async function createRecovery(db, askKey) {
+  const key = await askKey();
+  if (!key) return;
+  if (db.recovery && !(await confirm("A recovery phrase already exists, the old one will stop working. " + colors.amber("Replace") + " it"))) return;
+
+  const { phrase, recovery } = makeRecovery(key);
+  const old = db.recovery;
+  db.recovery = recovery;
+  if (!saveOrReport(dbPath, db, "Saved recovery phrase lock to db.json", "Error while saving recovery phrase!", "added")) {
+    db.recovery = old;
+    return void (process.exitCode = 1);
+  }
+
+  console.log();
+  log.warn("Write these 12 words down (in order) and keep them offline. They are shown only once.");
+  log.warn("Anyone with them + db.json can read every account.");
+  console.log();
+  console.log(formatPhrase(phrase));
+  console.log();
+  log.hint("(db.json.bak still holds the previous recovery lock until the next save)");
+
+  // make sure what's on paper is right, a typo there would only be found when it's needed
+  const { typed } = await prompt([{ type: "input", name: "typed", message: "Type the 12 words back to confirm you wrote them down:" }]);
+  if (normalizePhrase(typed) === phrase) return log.ok("Recovery phrase confirmed. Clear your terminal (e.g. 'clear') so it isn't left on screen.");
+  process.exitCode = 1;
+  log.error("Doesn't match what was shown. The new phrase is saved anyway, check your copy or run 'recovery' again to get a new one.");
+}
+
+// "word1 ... word12" -> numbered words in 3 columns (amber numbers, bold words)
+function formatPhrase(phrase) {
+  const words = phrase.split(" ");
+  const cell = (i) => colors.amber(String(i + 1).padStart(2) + ".") + " " + colors.bold.text(words[i].padEnd(12));
+  const rows = [];
+  for (let r = 0; r < 4; r++) rows.push("  " + [r, r + 4, r + 8].map(cell).join(" ").trimEnd());
+  return rows.join("\n");
+}
+
+// recovery phrase -> vault key -> new master password (rewrites credentials.json). For a lost credentials.json or a forgotten master password.
+async function recoverVault(db, cred) {
+  if (!db.recovery) {
+    process.exitCode = 1;
+    return log.error("db.json has no recovery phrase (restore credentials.json.bak, or db.json.bak if it had one)");
+  }
+  const phrase = await askPassword("RECOVERY PHRASE (12 words):");
+  const problem = checkPhrase(phrase);
+  if (problem) {
+    process.exitCode = 1;
+    return log.error("Invalid recovery phrase: " + problem);
+  }
+  const key = recover(phrase, db.recovery);
+  if (!key) {
+    process.exitCode = 1;
+    return log.error("Wrong recovery phrase!");
+  }
+  log.ok("Vault unlocked with the recovery phrase");
+  // same vault key, so db.json and the recovery phrase keep working as they are
+  if (!(await createMaster(cred, key, "New MASTER PASSWORD:"))) process.exitCode = 1;
+}
+
+module.exports = { createRecovery, recoverVault, formatPhrase };

package/options/update.js

@@ -0,0 +1,31 @@
+const { prompt, confirm, encrypt, saveOrReport, entryLabel, dbPath, FIELDS, SECRET_FIELDS, colors, log } = require("../utils");
+
+async function updateEntry(entry, db, key) {
+  if (!(await confirm("Entry " + entryLabel(entry) + " will be " + colors.amber("updated") + ", Are you sure"))) return;
+
+  log.hint("Enter = keep current value, '-' = clear it");
+  const questions = FIELDS.map((f) => ({ type: "input", name: f, message: "New " + f + " [" + (SECRET_FIELDS.includes(f) && entry[f] ? "***" : entry[f] || "") + "]: " }));
+  questions.push({ type: "password", name: "password", message: "New password (Enter = keep): " });
+
+  const answers = await prompt(questions);
+  let changed = false;
+  FIELDS.forEach((f) => {
+    const value = answers[f].trim();
+    let next = entry[f];
+    if (value === "-" && f !== "name") next = "";
+    else if (value !== "" && value !== "-") next = SECRET_FIELDS.includes(f) ? encrypt(value, key) : value; // secrets: new value always counts as a change
+    if (next !== entry[f]) changed = true;
+    entry[f] = next;
+  });
+  if (answers.password !== "") {
+    entry.password = encrypt(answers.password, key);
+    changed = true;
+  }
+  if (!changed) return log.hint("Nothing changed");
+  entry.updated = new Date().toISOString();
+
+  // entry is a reference into db.accounts
+  saveOrReport(dbPath, db, "Updated entry #" + entry.id, "Error while updating entry!", "updated");
+}
+
+module.exports = updateEntry;

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "keebox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.1",
+  "description": "KeeBox is an offline password manager that lives in your terminal",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eissapk/keebox.git"
+  },
+  "keywords": [],
+  "author": "Eissa Saber",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/eissapk/keebox/issues"
+  },
+  "homepage": "https://github.com/eissapk/keebox#readme"
+}

package/test/check.test.js

@@ -0,0 +1,66 @@
+// run: npm test  (or: node --test)
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+const crypto = require("crypto");
+const { encrypt, lockVault } = require("../utils");
+const { checkEntry, checkEntries, checkCredentials } = require("../options/check");
+
+const key = crypto.randomBytes(32);
+const otherKey = crypto.randomBytes(32);
+const good = (id, extra = {}) => ({ id, name: "github", url: "github.com", username: "foo", login: encrypt("me", key), notes: "", password: encrypt("pw", key), created: "2026-01-01T00:00:00.000Z", updated: "2026-01-01T00:00:00.000Z", ...extra });
+
+describe("checkEntry", () => {
+  test("healthy entry, with and without the key", () => {
+    assert.deepEqual(checkEntry(good(1), key), []);
+    assert.deepEqual(checkEntry(good(1), null), []);
+    assert.deepEqual(checkEntry({ id: 2, name: "old", password: encrypt("pw", key) }, key), []); // before timestamps/secret fields existed
+  });
+
+  test("finds values that can't be decrypted (wrong key or flipped byte)", () => {
+    const pw = encrypt("pw", key);
+    const flipped = pw.slice(0, -1) + (pw.slice(-1) === "0" ? "1" : "0");
+    assert.deepEqual(checkEntry(good(1, { password: flipped }), key), ["password can't be decrypted (damaged)"]);
+    assert.deepEqual(checkEntry(good(1, { notes: encrypt("n", otherKey) }), key), ["notes can't be decrypted (damaged)"]);
+    assert.deepEqual(checkEntry(good(1, { password: flipped }), null), []); // structure only
+  });
+
+  test("finds broken structure", () => {
+    assert.deepEqual(checkEntry(null, key), ["not an account object"]);
+    assert.deepEqual(checkEntry(good("1", { name: " ", password: "", login: "plain", created: "nope" }), key), [
+      'bad id ("1")',
+      "name is empty",
+      "password is empty",
+      "login isn't encrypted (unknown format)",
+      "created isn't a valid date",
+    ]);
+  });
+});
+
+describe("checkEntries", () => {
+  test("returns only damaged entries, flags duplicate ids", () => {
+    const damaged = checkEntries([good(1), good(2), good(2), good(3, { password: "x" })], key);
+    assert.deepEqual(
+      damaged.map((d) => [d.entry.id, d.problems]),
+      [
+        [2, ["duplicate id (2 entries use #2)"]],
+        [2, ["duplicate id (2 entries use #2)"]],
+        [3, ["password isn't encrypted (unknown format)"]],
+      ]
+    );
+  });
+});
+
+describe("checkCredentials", () => {
+  test("healthy credentials", () => {
+    assert.deepEqual(checkCredentials(lockVault("master", key), [good(1)]), []);
+  });
+
+  test("missing master password is only a problem when db has encrypted entries", () => {
+    assert.deepEqual(checkCredentials({}, []), []);
+    assert.match(checkCredentials({}, [good(1)])[0], /no master password/);
+  });
+
+  test("bad salt / n / key", () => {
+    assert.deepEqual(checkCredentials({ salt: "zz", n: 1000, key: "nope" }, []), ["credentials.json: bad salt", "credentials.json: bad n (must be a power of 2)", "credentials.json: key isn't encrypted (unknown format)"]);
+  });
+});

package/test/crypto.test.js

@@ -0,0 +1,200 @@
+// run: npm test  (or: node --test)
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+const crypto = require("crypto");
+// load through utils/index.js: it wires vault.js in at the end (loading vault.js first breaks config.js)
+const { encrypt, decrypt, decryptField, mkPass, lockVault, hasMaster, unlock } = require("../utils");
+
+const FORMAT = /^[0-9a-f]{24}\.[0-9a-f]{32}\.[0-9a-f]*$/; // "iv.tag.data"
+const newKey = () => crypto.randomBytes(32);
+
+// flip one hex digit of part `i` ("iv" = 0, "tag" = 1, "data" = 2)
+function tamper(str, i) {
+  const parts = str.split(".");
+  const p = parts[i];
+  parts[i] = (p[0] === "0" ? "1" : "0") + p.slice(1);
+  return parts.join(".");
+}
+
+describe("encrypt / decrypt", () => {
+  test("round-trips text", () => {
+    const key = newKey();
+    for (const text of ["hunter2", "", "ünïcødé 🔑 كلمة", "a".repeat(10000), "with.dots.inside"]) {
+      assert.equal(decrypt(encrypt(text, key), key), text);
+    }
+  });
+
+  test('output is "iv.tag.data" hex', () => {
+    const out = encrypt("secret", newKey());
+    assert.match(out, FORMAT);
+    assert.equal(out.split(".")[2].length, "secret".length * 2); // GCM: ciphertext length = plaintext length
+  });
+
+  test("ciphertext does not contain the plaintext", () => {
+    const text = "plain-text-password";
+    const out = encrypt(text, newKey());
+    assert.ok(!out.includes(text));
+    assert.ok(!out.includes(Buffer.from(text).toString("hex")));
+  });
+
+  test("uses a fresh IV every time", () => {
+    const key = newKey();
+    const a = encrypt("same", key);
+    const b = encrypt("same", key);
+    assert.notEqual(a, b);
+    assert.notEqual(a.split(".")[0], b.split(".")[0]);
+  });
+
+  test("wrong key throws", () => {
+    const out = encrypt("secret", newKey());
+    assert.throws(() => decrypt(out, newKey()));
+  });
+
+  test("tampered iv, tag or data throws", () => {
+    const key = newKey();
+    const out = encrypt("secret", key);
+    for (const i of [0, 1, 2]) assert.throws(() => decrypt(tamper(out, i), key), `part ${i}`);
+  });
+
+  test("truncated ciphertext throws", () => {
+    const key = newKey();
+    const out = encrypt("secret", key);
+    assert.throws(() => decrypt(out.slice(0, -2), key));
+  });
+
+  test("rejects strings that aren't in the encrypt() format", () => {
+    const key = newKey();
+    for (const bad of ["", "plaintext", "a.b.c", "00.11.22", encrypt("x", key).toUpperCase(), undefined, null]) {
+      assert.throws(() => decrypt(bad, key), /unknown encryption format/, String(bad));
+    }
+  });
+
+  test("rejects keys that aren't 256-bit", () => {
+    assert.throws(() => encrypt("x", crypto.randomBytes(16)));
+  });
+});
+
+describe("decryptField", () => {
+  // silences console.error and restores process.exitCode
+  function quietly(fn) {
+    const { error } = console;
+    const code = process.exitCode;
+    const logged = [];
+    console.error = (...args) => logged.push(args.join(" "));
+    try {
+      return { result: fn(), exitCode: process.exitCode, logged };
+    } finally {
+      console.error = error;
+      process.exitCode = code;
+    }
+  }
+
+  test("decrypts a field", () => {
+    const key = newKey();
+    assert.equal(decryptField({ id: 1, notes: encrypt("my notes", key) }, "notes", key), "my notes");
+  });
+
+  test('empty or missing field -> ""', () => {
+    const key = newKey();
+    assert.equal(decryptField({ id: 1, notes: "" }, "notes", key), "");
+    assert.equal(decryptField({ id: 1 }, "notes", key), "");
+  });
+
+  test("damaged field -> null, error printed, exit code 1", () => {
+    const key = newKey();
+    const entry = { id: 7, notes: tamper(encrypt("x", key), 2) };
+    const { result, exitCode, logged } = quietly(() => decryptField(entry, "notes", key));
+    assert.equal(result, null);
+    assert.equal(exitCode, 1);
+    assert.match(logged.join("\n"), /notes of entry #7/);
+  });
+});
+
+describe("mkPass", () => {
+  const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^a-zA-Z0-9]/];
+
+  test("has the exact length", () => {
+    for (const n of [4, 5, 8, 16, 32, 64, 128]) assert.equal(mkPass(n).length, n);
+  });
+
+  test("always has one char of each class", () => {
+    for (let i = 0; i < 500; i++) {
+      const p = mkPass(4); // shortest: exactly one of each
+      for (const re of classes) assert.match(p, re);
+    }
+  });
+
+  test("uses only printable ASCII, no spaces", () => {
+    for (let i = 0; i < 100; i++) assert.match(mkPass(32), /^[\x21-\x7e]+$/);
+  });
+
+  test("doesn't repeat", () => {
+    const seen = new Set();
+    for (let i = 0; i < 1000; i++) seen.add(mkPass(16));
+    assert.equal(seen.size, 1000);
+  });
+
+  test("required chars aren't stuck in fixed positions (shuffled)", () => {
+    // without the shuffle, position 0 would always be lowercase
+    const firsts = new Set();
+    for (let i = 0; i < 200; i++) {
+      const c = mkPass(4)[0];
+      firsts.add(classes.findIndex((re) => re.test(c)));
+    }
+    assert.equal(firsts.size, 4);
+  });
+});
+
+describe("vault (master password)", () => {
+  // scrypt is slow on purpose (~100ms per call), so share one locked vault
+  const password = "correct horse battery staple";
+  const vaultKey = newKey();
+  const cred = lockVault(password, vaultKey);
+
+  test("lockVault -> { salt, n, key }", () => {
+    assert.deepEqual(Object.keys(cred).sort(), ["key", "n", "salt"]);
+    assert.match(cred.salt, /^[0-9a-f]{32}$/);
+    assert.equal(cred.n, 32768);
+    assert.match(cred.key, FORMAT);
+    assert.ok(!cred.key.includes(vaultKey.toString("hex")));
+  });
+
+  test("right password unlocks the vault key", () => {
+    const key = unlock(password, cred);
+    assert.ok(Buffer.isBuffer(key));
+    assert.ok(key.equals(vaultKey));
+  });
+
+  test("wrong password -> null", () => {
+    assert.equal(unlock("wrong", cred), null);
+    assert.equal(unlock("", cred), null);
+    assert.equal(unlock(password + " ", cred), null); // callers trim, unlock itself doesn't
+  });
+
+  test("tampered credentials -> null", () => {
+    assert.equal(unlock(password, { ...cred, key: tamper(cred.key, 2) }), null);
+    assert.equal(unlock(password, { ...cred, salt: tamper(cred.salt, 0) }), null);
+    assert.equal(unlock(password, { ...cred, n: 16384 }), null);
+  });
+
+  test("re-locking uses a new salt, old and new both open the same key", () => {
+    const again = lockVault(password, vaultKey);
+    assert.notEqual(again.salt, cred.salt);
+    assert.notEqual(again.key, cred.key);
+    assert.ok(unlock(password, again).equals(vaultKey));
+  });
+
+  test("changing the master password keeps the vault key, so existing entries still decrypt", () => {
+    const entry = encrypt("site password", vaultKey);
+    const changed = lockVault("new master", unlock(password, cred));
+    assert.equal(unlock(password, changed), null);
+    assert.equal(decrypt(entry, unlock("new master", changed)), "site password");
+  });
+
+  test("hasMaster / unlock before a master password exists", () => {
+    assert.equal(hasMaster(cred), true);
+    assert.equal(hasMaster({}), false);
+    assert.equal(hasMaster({ key: "" }), false);
+    assert.equal(unlock(password, {}), null);
+  });
+});

package/test/export.test.js

@@ -0,0 +1,56 @@
+// run: npm test  (or: node --test)
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+const crypto = require("crypto");
+const { encrypt } = require("../utils");
+const { toCsv } = require("../utils/csv");
+const { entriesToCsv } = require("../options/export");
+
+describe("toCsv", () => {
+  test("plain fields stay unquoted, rows end with CRLF", () => {
+    assert.equal(toCsv([["a", "b"], [1, ""]]), "a,b\r\n1,\r\n");
+  });
+
+  test("quotes fields with commas, quotes and line breaks", () => {
+    assert.equal(toCsv([['a,b', 'say "hi"', "l1\nl2", "x\ry"]]), '"a,b","say ""hi""","l1\nl2","x\ry"\r\n');
+  });
+
+  test("keeps leading = + - @ as-is", () => {
+    assert.equal(toCsv([["=1+1", "-x", "@y"]]), "=1+1,-x,@y\r\n");
+  });
+
+  test("null / undefined become empty fields", () => {
+    assert.equal(toCsv([[null, undefined, 0]]), ",,0\r\n");
+  });
+});
+
+describe("entriesToCsv", () => {
+  const key = crypto.randomBytes(32);
+  const entry = {
+    id: 1, name: "github", url: "github.com", username: "foo",
+    login: encrypt("foo@mail.com", key), notes: encrypt("2FA, phone", key), password: encrypt('p"w,1', key),
+    created: "2026-01-01T00:00:00.000Z", updated: "2026-01-02T00:00:00.000Z",
+  };
+
+  test("decrypts secrets into the right columns", () => {
+    const csv = entriesToCsv([entry, { id: 2, name: "x", url: "", username: "", login: "", notes: "", password: encrypt("p", key) }], key);
+    assert.equal(
+      csv,
+      "id,name,url,username,login,notes,password,created,updated\r\n" +
+        '1,github,github.com,foo,foo@mail.com,"2FA, phone","p""w,1",2026-01-01T00:00:00.000Z,2026-01-02T00:00:00.000Z\r\n' +
+        "2,x,,,,,p,,\r\n"
+    );
+  });
+
+  test("returns null with a wrong key (nothing partial)", () => {
+    const exitCode = process.exitCode;
+    const error = console.error;
+    console.error = () => {};
+    try {
+      assert.equal(entriesToCsv([entry], crypto.randomBytes(32)), null);
+    } finally {
+      console.error = error;
+      process.exitCode = exitCode;
+    }
+  });
+});

package/test/import.test.js

@@ -0,0 +1,43 @@
+// run: npm test  (or: node --test)
+const { test, describe } = require("node:test");
+const assert = require("node:assert/strict");
+const { toCsv, parseCsv } = require("../utils/csv");
+const { rowsToRecords } = require("../options/import");
+
+describe("parseCsv", () => {
+  test("round-trips toCsv output", () => {
+    const rows = [["id", "notes", "password"], ["1", 'a, "b"\nline 2', "=x"], ["2", "", "-y"], ["3", "\r\n", '"']];
+    assert.deepEqual(parseCsv(toCsv(rows)), rows);
+  });
+
+  test("accepts LF, BOM, no trailing newline, skips blank lines", () => {
+    assert.deepEqual(parseCsv("a,b\n\n1,2\n\n3,"), [["a", "b"], ["1", "2"], ["3", ""]]);
+  });
+
+  test("empty quoted fields", () => {
+    assert.deepEqual(parseCsv('"",x,""\r\n'), [["", "x", ""]]);
+  });
+
+  test("throws on an unclosed quote or text after a closing quote", () => {
+    assert.throws(() => parseCsv('a\n"b,c\n'), /unclosed quote \(line 2\)/);
+    assert.throws(() => parseCsv('"a"b,c\n'), /after closing quote/);
+  });
+});
+
+describe("rowsToRecords", () => {
+  test("maps columns by header name, any order / case, ignores unknown ones", () => {
+    const { records, errors } = rowsToRecords([["Password", "ID", " Name ", "extra"], ["pw", "7", " github ", "?"]]);
+    assert.deepEqual(errors, []);
+    assert.deepEqual(records, [{ password: "pw", id: "7", name: "github", extra: "?" }]);
+  });
+
+  test("requires name and password columns", () => {
+    assert.match(rowsToRecords([["name", "url"], ["a", "b"]]).errors[0], /missing column\(s\): password/);
+    assert.match(rowsToRecords([]).errors[0], /empty/);
+  });
+
+  test("reports rows with a wrong column count or an empty name", () => {
+    const { errors } = rowsToRecords([["name", "password"], ["a"], [" ", "pw"], ["ok", "pw"]]);
+    assert.deepEqual(errors, ["row 1: has 1 columns, header has 2", "row 2: name is empty"]);
+  });
+});