@nightlybuildgroup/vault 1.2.0 → 1.3.0

package/README.md

@@ -32,6 +32,7 @@ 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
@@ -39,6 +40,71 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightlybuildgroup/vault",
-  "version": "1.2.0",
+  "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

@@ -102,6 +102,58 @@ export async function getCardField({ item, field, session }, deps = {}) {
   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,7 @@ 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)
@@ -46,9 +47,10 @@ export async function runCli(argv, deps = {}) {
 }
 
 async function loadCommands() {
-  const [setup, get, list, 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'),
@@ -58,6 +60,7 @@ async function loadCommands() {
   return {
     setup: setup.default,
     get: get.default,
+    add: add.default,
     list: list.default,
     status: status.default,
     doctor: doctor.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/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; });