@nightlybuildgroup/vault 1.1.2 → 1.3.0

package/README.md

@@ -30,6 +30,9 @@ password. Credentials are verified against the server before anything is saved.
 nbg-pw get "GitHub"                 # prints the password
 nbg-pw get "GitHub" --field username   # a built-in field
 nbg-pw get "GitHub" --custom apiToken  # a custom field, looked up by name
+nbg-pw get "My Visa" --field number    # a credit-card field (see below)
+nbg-pw list "My Visa"               # show an item's field names + types, no values
+printf '%s' "$pw" | nbg-pw add "GitHub" --username octocat --password-stdin
 nbg-pw serve --port 8087            # local bw REST API for fast repeated reads
 nbg-pw status                       # presence + auth state (no secrets)
 nbg-pw doctor                       # diagnose bw / Keychain / connectivity
@@ -37,6 +40,100 @@ nbg-pw logout                       # lock the session
 nbg-pw reset                        # log out and delete stored credentials
 ```
 
+### Adding items (`add`)
+
+Creates a **login** item. The password never goes on the command line (it would
+be visible in `ps`) — it's read from stdin, or supplied via `--json`.
+
+```sh
+# Flag mode — password piped on stdin:
+printf '%s' "$pw" | nbg-pw add "GitHub" \
+  --username octocat \
+  --url https://github.com \
+  --notes "work account" \
+  --folder "Agents" \
+  --field plan=pro \
+  --field-hidden token="$tok" \
+  --password-stdin
+```
+
+Options: `--username`, `--url` (repeatable), `--notes`, `--folder` (resolved by
+name, **created if missing**), `--collection` / `--organization` (shares the item
+into an org collection), `--field name=value` (text, repeatable),
+`--field-hidden name=value` (hidden, repeatable), `--totp`. On success it prints
+`Created "<name>" (<id>)` — never any secret value.
+
+> Note: in flag mode, `--field-hidden` values still pass through argv. For
+> secret custom fields use `--json` (below), which keeps **everything** off the
+> command line.
+
+#### JSON mode — secret-safe bulk automation
+
+`nbg-pw add --json` reads one entry as a JSON object on stdin, so every value
+(password, hidden fields, notes) stays off argv:
+
+```sh
+jq -n --arg name GitHub --arg u octocat --arg p "$pw" --arg t "$tok" \
+  '{name:$name, username:$u, password:$p, uris:["https://github.com"],
+    folder:"Agents", fields:[{name:"token", value:$t, type:1}]}' \
+  | nbg-pw add --json
+```
+
+Accepted keys: `name` (required), `username`, `password`, `uris` (array),
+`notes`, `totp`, `folder`, `collection`, `organization`, and `fields`
+(`[{name, value, type}]`; type `0` = text, `1` = hidden).
+
+#### Migrating a KeePass `.kdbx` to Bitwarden
+
+Loop your KeePass entries and pipe each into `add --json` — secrets flow through
+stdin only:
+
+```sh
+DB=~/Documents/Agents.kdbx
+for path in $(keepassxc-cli ls -R -f "$DB"); do
+  [ "${path%/}" != "$path" ] && continue   # skip groups
+  user=$(keepassxc-cli show -q -a UserName "$DB" "$path")
+  pass=$(keepassxc-cli show -q -a Password "$DB" "$path")
+  url=$( keepassxc-cli show -q -a URL      "$DB" "$path")
+  group=$(dirname "$path")
+  jq -n --arg n "$(basename "$path")" --arg u "$user" --arg p "$pass" \
+        --arg url "$url" --arg f "$group" \
+     '{name:$n, username:$u, password:$p,
+       uris:(if $url=="" then [] else [$url] end),
+       folder:(if $f=="." then null else $f end)}' \
+    | nbg-pw add --json
+done
+```
+
+### Credit-card items
+
+Credit cards have no username or password — just card data. `bw` has no native
+getter for those, so `nbg-pw` reads them from the item and exposes each as a
+`--field`:
+
+```sh
+nbg-pw get "My Visa" --field number       # card number
+nbg-pw get "My Visa" --field cvv           # security code (alias: code)
+nbg-pw get "My Visa" --field expiration    # "MM/YYYY" (alias: exp)
+nbg-pw get "My Visa" --field cardholder    # cardholder name
+nbg-pw get "My Visa" --field brand         # e.g. Visa
+```
+
+### Discovering fields with `list`
+
+Not sure what a custom field is called, or which fields an item has? `list`
+prints the item type, the built-in fields you can `get`, and every custom field
+name with its type — **never any values**:
+
+```sh
+$ nbg-pw list "My Visa"
+Type: card
+Built-in: number, cvv, expiration, cardholder, brand
+Custom fields:
+  billingZip  (text)
+  pin         (hidden)
+```
+
 ### Reading custom fields over `serve`
 
 `serve` is a thin wrapper around Bitwarden's own `bw serve` REST API, which has

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightlybuildgroup/vault",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Store Vaultwarden/Bitwarden credentials in the macOS Keychain and read secrets back for local agents.",
   "type": "module",
   "bin": {

package/src/bw.js

@@ -51,17 +51,109 @@ export async function getItem({ item, field, session }, deps = {}) {
   return stdout.replace(/\n$/, '');
 }
 
-export async function getCustomField({ item, name, session }, deps = {}) {
+export async function getItemJson({ item, session }, deps = {}) {
   const run = deps.run ?? realRun;
   const { stdout } = await run('bw', ['get', 'item', item], {
     env: { BW_SESSION: session },
   });
-  const parsed = JSON.parse(stdout);
+  return JSON.parse(stdout);
+}
+
+export async function getCustomField({ item, name, session }, deps = {}) {
+  const parsed = await getItemJson({ item, session }, deps);
   const match = (parsed.fields ?? []).find((f) => f.name === name);
   if (!match) throw new Error(`item "${item}" has no custom field "${name}"`);
   return match.value;
 }
 
+// Credit-card items have no native `bw get <field>` getter, so card fields are
+// read from the item's `card` object. Maps user-facing field names (and a few
+// aliases) onto the bw card-object keys; `expiration` is computed, not a key.
+const CARD_FIELD_ALIASES = {
+  number: 'number',
+  cvv: 'code',
+  code: 'code',
+  securitycode: 'code',
+  expiration: 'expiration',
+  exp: 'expiration',
+  cardholder: 'cardholderName',
+  cardholdername: 'cardholderName',
+  brand: 'brand',
+};
+
+export function isCardField(field) {
+  return Object.prototype.hasOwnProperty.call(CARD_FIELD_ALIASES, String(field).toLowerCase());
+}
+
+export async function getCardField({ item, field, session }, deps = {}) {
+  const parsed = await getItemJson({ item, session }, deps);
+  const card = parsed.card;
+  if (!card) throw new Error(`item "${item}" is not a credit card`);
+  const key = CARD_FIELD_ALIASES[String(field).toLowerCase()];
+  if (key === 'expiration') {
+    if (!card.expMonth && !card.expYear) throw new Error(`item "${item}" has no expiration date`);
+    const mm = String(card.expMonth ?? '').padStart(2, '0');
+    return `${mm}/${card.expYear ?? ''}`;
+  }
+  const value = card[key];
+  if (value === undefined || value === null || value === '') {
+    throw new Error(`item "${item}" has no ${field}`);
+  }
+  return String(value);
+}
+
+// `bw create`/`bw move` read the object as base64 JSON. We pass it on stdin
+// (never argv), so secret values in the payload stay off the process list.
+function encode(obj) {
+  return Buffer.from(JSON.stringify(obj)).toString('base64');
+}
+
+export async function createItem({ item, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['create', 'item'], {
+    env: { BW_SESSION: session },
+    input: encode(item),
+  });
+  return JSON.parse(stdout);
+}
+
+export async function listFolders({ session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['list', 'folders'], { env: { BW_SESSION: session } });
+  return JSON.parse(stdout);
+}
+
+export async function createFolder({ name, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['create', 'folder'], {
+    env: { BW_SESSION: session },
+    input: encode({ name }),
+  });
+  return JSON.parse(stdout);
+}
+
+export async function listCollections({ session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['list', 'collections'], { env: { BW_SESSION: session } });
+  return JSON.parse(stdout);
+}
+
+export async function listOrganizations({ session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['list', 'organizations'], { env: { BW_SESSION: session } });
+  return JSON.parse(stdout);
+}
+
+// Share an existing item into an organization's collection(s). This is bw's only
+// path to put an item in a collection; the item must already exist.
+export async function moveItemToCollection({ itemId, organizationId, collectionIds, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  await run('bw', ['move', itemId, organizationId], {
+    env: { BW_SESSION: session },
+    input: encode(collectionIds),
+  });
+}
+
 export async function status(deps = {}) {
   const run = deps.run ?? realRun;
   const { stdout } = await run('bw', ['status']);

package/src/cli.js

@@ -5,6 +5,8 @@ Usage: nbg-pw <command> [options]
 Commands:
   setup     Interactive wizard: store your Vaultwarden credentials in the Keychain
   get       Fetch a secret value (e.g. nbg-pw get "GitHub" --field password)
+  add       Create a login item (flags or --json on stdin; for kdbx → bw imports)
+  list      Show an item's field names + types, no values (nbg-pw list "My Visa")
   serve     Start a local bw API daemon (unlocked) for fast repeated reads
   status    Show config + auth state (no secret values)
   doctor    Diagnose bw / Keychain / server connectivity (--fix resets a wedged bw session)
@@ -45,9 +47,11 @@ export async function runCli(argv, deps = {}) {
 }
 
 async function loadCommands() {
-  const [setup, get, status, doctor, serve, reset] = await Promise.all([
+  const [setup, get, add, list, status, doctor, serve, reset] = await Promise.all([
     import('./commands/setup.js'),
     import('./commands/get.js'),
+    import('./commands/add.js'),
+    import('./commands/list.js'),
     import('./commands/status.js'),
     import('./commands/doctor.js'),
     import('./commands/serve.js'),
@@ -56,6 +60,8 @@ async function loadCommands() {
   return {
     setup: setup.default,
     get: get.default,
+    add: add.default,
+    list: list.default,
     status: status.default,
     doctor: doctor.default,
     serve: serve.default,

package/src/commands/add.js

@@ -0,0 +1,163 @@
+import * as bwModule from '../bw.js';
+import * as keychainModule from '../keychain.js';
+
+const USAGE =
+  'usage: nbg-pw add <name> [--username <u>] [--url <uri>]... [--notes <n>] ' +
+  '[--folder <name>] [--collection <name>] [--organization <name|id>] ' +
+  '[--field <name>=<value>]... [--field-hidden <name>=<value>]... [--totp <secret>] ' +
+  '[--password-stdin]\n   or: nbg-pw add --json   (reads one entry as a JSON object on stdin)';
+
+// `--field name=value` → { name, value, type }. Splits on the FIRST `=` so the
+// value may itself contain `=`.
+function parseField(raw, type) {
+  const eq = raw.indexOf('=');
+  if (eq === -1) throw new Error(`--field expects name=value, got "${raw}"`);
+  return { name: raw.slice(0, eq), value: raw.slice(eq + 1), type };
+}
+
+export function parseAddArgs(args) {
+  const opts = { uris: [], fields: [], passwordStdin: false, json: false };
+  let name = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const need = () => {
+      const v = args[++i];
+      if (v === undefined) throw new Error(`${a} requires a value`);
+      return v;
+    };
+    switch (a) {
+      case '--json': opts.json = true; break;
+      case '--password-stdin': opts.passwordStdin = true; break;
+      case '--username': opts.username = need(); break;
+      case '--url': opts.uris.push(need()); break;
+      case '--notes': opts.notes = need(); break;
+      case '--folder': opts.folder = need(); break;
+      case '--collection': opts.collection = need(); break;
+      case '--organization': opts.organization = need(); break;
+      case '--totp': opts.totp = need(); break;
+      case '--field': opts.fields.push(parseField(need(), 0)); break;
+      case '--field-hidden': opts.fields.push(parseField(need(), 1)); break;
+      default:
+        if (a.startsWith('--')) throw new Error(`unknown option "${a}"\n${USAGE}`);
+        if (name === null) name = a;
+        else throw new Error(`unexpected argument "${a}"\n${USAGE}`);
+    }
+  }
+  if (!opts.json && name === null) throw new Error(USAGE);
+  opts.name = name;
+  return opts;
+}
+
+// Turns a normalized entry into the Bitwarden login-item JSON shape.
+export function buildLoginItem(entry) {
+  const item = {
+    type: 1,
+    name: entry.name,
+    notes: entry.notes ?? null,
+    login: {
+      username: entry.username ?? null,
+      password: entry.password ?? null,
+      uris: (entry.uris ?? []).filter(Boolean).map((uri) => ({ match: null, uri })),
+      totp: entry.totp ?? null,
+    },
+    fields: (entry.fields ?? []).map((f) => ({ name: f.name, value: f.value ?? '', type: f.type ?? 0 })),
+  };
+  if (entry.folderId) item.folderId = entry.folderId;
+  return item;
+}
+
+async function resolveFolderId(bw, session, folderName) {
+  const folders = await bw.listFolders({ session });
+  const found = folders.find((f) => f.name === folderName && f.id);
+  if (found) return found.id;
+  const created = await bw.createFolder({ name: folderName, session });
+  return created.id;
+}
+
+async function resolveCollection(bw, session, collectionName, org) {
+  const collections = await bw.listCollections({ session });
+  let matches = collections.filter((c) => c.name === collectionName);
+  if (org) {
+    const orgs = await bw.listOrganizations({ session });
+    const match = orgs.find((o) => o.id === org || o.name === org);
+    const orgId = match ? match.id : org;
+    matches = matches.filter((c) => c.organizationId === orgId);
+  }
+  if (matches.length === 0) {
+    throw new Error(`no collection named "${collectionName}"${org ? ` in organization "${org}"` : ''}`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`multiple collections named "${collectionName}"; disambiguate with --organization <name|id>`);
+  }
+  return matches[0];
+}
+
+export async function runAdd(args, deps) {
+  const { keychain, bw, out, err, readStdin } = deps;
+  const opts = parseAddArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  let entry;
+  if (opts.json) {
+    const parsed = JSON.parse(await readStdin());
+    if (!parsed.name) throw new Error('json entry requires a "name"');
+    entry = parsed;
+  } else {
+    entry = {
+      name: opts.name,
+      username: opts.username,
+      uris: opts.uris,
+      notes: opts.notes,
+      totp: opts.totp,
+      fields: opts.fields,
+      folder: opts.folder,
+      collection: opts.collection,
+      organization: opts.organization,
+    };
+    if (opts.passwordStdin) entry.password = (await readStdin()).replace(/\r?\n$/, '');
+  }
+
+  const session = await bw.ensureSession(config);
+
+  if (entry.folder) entry.folderId = await resolveFolderId(bw, session, entry.folder);
+
+  const created = await bw.createItem({ item: buildLoginItem(entry), session });
+
+  if (entry.collection) {
+    const col = await resolveCollection(bw, session, entry.collection, entry.organization);
+    await bw.moveItemToCollection({
+      itemId: created.id,
+      organizationId: col.organizationId,
+      collectionIds: [col.id],
+      session,
+    });
+  }
+
+  out(`Created "${created.name}" (${created.id})\n`);
+  return 0;
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+export default async function add(args) {
+  return runAdd(args, {
+    keychain: keychainModule,
+    bw: bwModule,
+    readStdin,
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  });
+}

package/src/commands/get.js

@@ -20,7 +20,7 @@ export function parseGetArgs(args) {
     }
     else if (!item) { item = args[i]; }
   }
-  if (!item) throw new Error('usage: nbg-pw get <item> [--field password|username|uri|notes] [--custom <name>]');
+  if (!item) throw new Error('usage: nbg-pw get <item> [--field password|username|uri|notes|number|cvv|expiration|cardholder|brand] [--custom <name>]');
   if (fieldGiven && custom !== null) throw new Error('--field and --custom are mutually exclusive');
   const result = { item, field };
   if (custom !== null) result.custom = custom;
@@ -38,9 +38,14 @@ export async function runGet(args, deps) {
   }
 
   const session = await bw.ensureSession(config);
-  const value = custom !== undefined
-    ? await bw.getCustomField({ item, name: custom, session })
-    : await bw.getItem({ item, field, session });
+  let value;
+  if (custom !== undefined) {
+    value = await bw.getCustomField({ item, name: custom, session });
+  } else if (bw.isCardField?.(field)) {
+    value = await bw.getCardField({ item, field, session });
+  } else {
+    value = await bw.getItem({ item, field, session });
+  }
   out(value + '\n');
   return 0;
 }

package/src/commands/list.js

@@ -0,0 +1,85 @@
+import * as bwModule from '../bw.js';
+import * as keychainModule from '../keychain.js';
+
+const ITEM_TYPES = { 1: 'login', 2: 'note', 3: 'card', 4: 'identity' };
+const FIELD_TYPE_LABELS = { 0: 'text', 1: 'hidden', 2: 'boolean', 3: 'linked' };
+
+export function parseListArgs(args) {
+  let item = null;
+  for (const a of args) {
+    if (!item) item = a;
+  }
+  if (!item) throw new Error('usage: nbg-pw list <item>');
+  return { item };
+}
+
+// The built-in (non-custom) fields you can `nbg-pw get` for this item — only the
+// ones actually populated, so the list mirrors what a `get` would return.
+function builtinFields(parsed) {
+  if (parsed.type === 3 && parsed.card) {
+    const c = parsed.card;
+    return [
+      c.number && 'number',
+      c.code && 'cvv',
+      (c.expMonth || c.expYear) && 'expiration',
+      c.cardholderName && 'cardholder',
+      c.brand && 'brand',
+    ].filter(Boolean);
+  }
+  if (parsed.type === 1 && parsed.login) {
+    const l = parsed.login;
+    return [
+      l.username && 'username',
+      l.password && 'password',
+      l.uris && l.uris.length && 'uri',
+      l.totp && 'totp',
+      parsed.notes && 'notes',
+    ].filter(Boolean);
+  }
+  return parsed.notes ? ['notes'] : [];
+}
+
+export function formatItem(parsed) {
+  const lines = [`Type: ${ITEM_TYPES[parsed.type] ?? `unknown (${parsed.type})`}`];
+
+  const builtin = builtinFields(parsed);
+  if (builtin.length) lines.push(`Built-in: ${builtin.join(', ')}`);
+
+  const fields = parsed.fields ?? [];
+  if (fields.length === 0) {
+    lines.push('Custom fields: (none)');
+  } else {
+    lines.push('Custom fields:');
+    const width = Math.max(...fields.map((f) => f.name.length));
+    for (const f of fields) {
+      const label = FIELD_TYPE_LABELS[f.type] ?? `type ${f.type}`;
+      lines.push(`  ${f.name.padEnd(width)}  (${label})`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+export async function runList(args, deps) {
+  const { keychain, bw, out, err } = deps;
+  const { item } = parseListArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  const session = await bw.ensureSession(config);
+  const parsed = await bw.getItemJson({ item, session });
+  out(formatItem(parsed));
+  return 0;
+}
+
+export default async function list(args) {
+  return runList(args, {
+    keychain: keychainModule,
+    bw: bwModule,
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  });
+}

package/src/exec.js

@@ -5,6 +5,12 @@ export function run(cmd, args, opts = {}) {
   const doTrim = opts.trim !== false;
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, { env });
+    // `opts.input` is written to the child's stdin (used to pass base64-encoded
+    // JSON to `bw create`/`bw move` without exposing secrets on the command line).
+    if (opts.input != null) {
+      child.stdin.on('error', () => {}); // ignore EPIPE if the child closes stdin early
+      child.stdin.end(opts.input);
+    }
     let stdout = '';
     let stderr = '';
     child.stdout.on('data', (d) => { stdout += d; });