bwx 0.6.1 → 0.7.0

package/README.md

@@ -71,6 +71,7 @@ unlock. `valid` means reads work now, `stale` means the cached session was rejec
 |---------|-------------|
 | `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`) |
 | `bwx get totp <item>` | TOTP code (`--fresh [n]`, `--seed`) |
+| `bwx get <card field> <item>` | Card field (`number`, `cvv`, `cardholder`, `brand`, `expiry`, …) |
 | `bwx field <name> <item>` | Get custom field by name (same argument order as `get`) |
 | `bwx search <query>` | Search items (`--type`, `--folder`, `--limit`, `--full-items`) |
 | `bwx list [type]` | List items (`--type`, `--folder`, `--limit`, `--full-items`) |
@@ -139,6 +140,45 @@ Spaces, hyphens, and `=` padding are stripped and case is normalized; an `otpaut
 is stored verbatim so its parameters survive. Malformed secrets are rejected before the
 write, because a bad seed is otherwise discovered at the login it was supposed to unlock.
 
+### Cards
+
+Card items keep their values in a `card` object that `bw get <field>` cannot reach, so
+bwx reads them from the item itself — one vault read, no extra `bw` spawn:
+
+```bash
+bwx get number "Visa"        # 4111111111111111
+bwx get cvv "Visa"           # 123
+bwx get cardholder "Visa"    # Vladislav Forsh
+bwx get brand "Visa"         # Visa
+bwx get expiry "Visa"        # 03/2030
+bwx get expMonth "Visa"      # 03
+bwx get expYear "Visa"       # 2030
+```
+
+Names match leniently on case, dashes, and underscores, and bw's own JSON keys work too,
+so a name copied out of `bwx get item` resolves (`code` → `cvv`, `cardholderName` →
+`cardholder`, `exp-month` → `expMonth`).
+
+Two values are normalized rather than passed through, because the stored form is not the
+usable one:
+
+- `expMonth` is zero-padded — bw stores the month as typed (`3`), and every `MM` field
+  wants `03`.
+- `expiry` is composed from month and year, and is withheld entirely if either is missing
+  rather than handing back half a date.
+
+A card field only means the card object **on a card item**. `number`, `code`, and `brand`
+are plausible custom field names, so on any other item type they resolve as custom fields
+exactly as before — and if no such custom field exists, the error says which kind of item
+it actually is. `bwx field` is unchanged: custom fields only, never a card field.
+
+Grouping several card fields into one read is worth it — see [Secrets into a child
+process](#secrets-into-a-child-process):
+
+```bash
+bwx run --env NUM=number:Visa --env CVV=cvv:Visa --env EXP=expiry:Visa -- ./pay.sh
+```
+
 ### Listings are capped
 
 Listings stop at 50 items by default — an uncapped `bwx list` returns the whole vault,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bwx",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "keywords": [
     "bitwarden",

package/skill/bwx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bwx
-description: Bitwarden Extended CLI — retrieve, create, edit, delete vault items with auto-unlock. Use when the agent needs passwords, API keys, TOTP codes, custom fields, or vault management. Triggers on mentions of Bitwarden, bw, bwx, vault, password, secrets, TOTP, save key/token.
+description: Bitwarden Extended CLI — retrieve, create, edit, delete vault items with auto-unlock. Use when the agent needs passwords, API keys, TOTP codes, card details, custom fields, or vault management. Triggers on mentions of Bitwarden, bw, bwx, vault, password, secrets, TOTP, card number, CVV, save key/token.
 ---
 
 # bwx
@@ -17,6 +17,7 @@ bwx get username "GitHub"               # username
 bwx get notes "Deploy key"              # secure note content
 bwx get uri "GitHub"                    # first URI
 bwx get item "GitHub"                   # full item JSON
+bwx get number "Visa"                   # card number (also: cvv, expiry, cardholder, brand)
 bwx get "API Key" "Acme"                # custom field by name
 bwx field "API Key" "Acme"              # custom-field-only lookup, same arg order
 
@@ -45,6 +46,7 @@ echo "secret" | bwx create --name "Piped Note"
 ### `bwx get <field> <item>`
 
 Built-in fields: `password | username | totp | notes | uri | item`.
+Card items additionally take `number | cvv | cardholder | brand | expiry | expMonth | expYear`.
 Anything else is looked up as a custom field. Lists available fields on miss.
 
 A miss suggests near matches; an ambiguous name lists candidates with IDs. Read the
@@ -76,6 +78,27 @@ exactly are delegated to `bw get totp` instead of guessed at.
 Custom fields only, so an item whose custom field is named `password` is still reachable.
 Takes its arguments in the same order as `get` (this changed in 0.5.0).
 
+### Card fields
+
+```bash
+bwx get number "Visa"        # 4111111111111111
+bwx get cvv "Visa"           # 123        (bw's own key `code` works too)
+bwx get cardholder "Visa"    # Vladislav Forsh
+bwx get brand "Visa"         # Visa
+bwx get expiry "Visa"        # 03/2030    (composed; withheld if either half is missing)
+bwx get expMonth "Visa"      # 03         (zero-padded; bw stores "3")
+bwx get expYear "Visa"       # 2030
+```
+
+Read from the fetched item — `bw` has no card fields — so they cost one vault read and
+batch with each other under `bwx run`. Names match leniently on case, dashes, and
+underscores, and bw's JSON keys resolve (`code`, `cardholderName`, `exp-month`).
+
+A card field means the card object **only on a card item**. On any other type it resolves
+as a custom field of that name, since `number` and `code` are ordinary field names; the
+error names the item's actual type when no such field exists. `bwx field` never returns a
+card field.
+
 ### `bwx search <query>` / `bwx list [type]`
 
 Flags: `--type login|note|card|identity`, `--folder <name|id>`, `--limit <n>`, `--full-items`
@@ -108,7 +131,7 @@ bwx run --env DB_PASS=password:'Prod DB' -- ./migrate.sh
 bwx run --env TOKEN='API Key:Acme' --env USER=username:Acme -- ./deploy.sh
 ```
 
-- `--env` is repeatable; the field resolves as in `bwx get` (built-in, else custom field).
+- `--env` is repeatable; the field resolves as in `bwx get` (built-in, else card, else custom field).
 - Only the first `:` splits field from item, so `password:http://my.router` works.
 - Put `--` before the command when it takes its own flags.
 - Child stdio is inherited; bwx exits with the child's status (`128 + signal` if killed).

package/src/bw/cards.ts

@@ -0,0 +1,116 @@
+import type { BwCard } from "./types.ts";
+
+/**
+ * Card items keep their values in a `card` object rather than in `login` or in
+ * custom fields, and `bw get <field>` has no equivalent for any of them — so
+ * these names are resolved here, from an item bwx has already fetched.
+ *
+ * A reader returns the value or `null`; naming the item and raising is the
+ * caller's job, since it holds the item name and the error type.
+ */
+type CardReader = (card: BwCard) => string | null;
+
+/** Canonical names, in the order help text and errors list them. */
+export const CARD_FIELDS = [
+	"number",
+	"cvv",
+	"cardholder",
+	"brand",
+	"expiry",
+	"expMonth",
+	"expYear",
+] as const;
+
+export type CardField = (typeof CARD_FIELDS)[number];
+
+/**
+ * How each canonical field reads off the card object. Keyed by `CardField`, so
+ * adding a name to {@link CARD_FIELDS} without a reader fails to compile rather
+ * than at the one call that asks for it.
+ */
+const CARD_READERS: Record<CardField, CardReader> = {
+	number: (card) => text(card.number),
+	cvv: (card) => text(card.code),
+	cardholder: (card) => text(card.cardholderName),
+	brand: (card) => text(card.brand),
+	expiry: readExpiry,
+	expMonth: readExpMonth,
+	expYear: (card) => text(card.expYear),
+};
+
+/**
+ * Other spellings of the same fields: bw's own JSON keys, so a name copied out
+ * of `bwx get item` resolves, plus the words people reach for first.
+ */
+const CARD_ALIASES: Record<string, CardField> = {
+	code: "cvv",
+	cvc: "cvv",
+	securityCode: "cvv",
+	cardholderName: "cardholder",
+	holder: "cardholder",
+	exp: "expiry",
+	expiration: "expiry",
+};
+
+/**
+ * Card names are matched leniently — case, dashes, and underscores all collapse
+ * — because `expMonth`, `exp-month`, and `expmonth` are the same request, and
+ * failing one of them would only teach the caller to try the other two.
+ */
+function normalize(field: string): string {
+	return field.toLowerCase().replaceAll(/[-_\s]/g, "");
+}
+
+/**
+ * Every accepted spelling to its canonical field, derived so that the two
+ * tables above stay the only place a card field name is written down.
+ */
+const CANONICAL_BY_SPELLING: Record<string, CardField> = {
+	...Object.fromEntries(CARD_FIELDS.map((field) => [normalize(field), field])),
+	...Object.fromEntries(
+		Object.entries(CARD_ALIASES).map(([alias, field]) => [normalize(alias), field]),
+	),
+};
+
+/** True when `field` names a card field rather than a login field or a custom one. */
+export function isCardField(field: string): boolean {
+	return normalize(field) in CANONICAL_BY_SPELLING;
+}
+
+/** Reads one card field, or `null` when the card carries no value for it. */
+export function readCardValue(card: BwCard, field: string): string | null {
+	const canonical = CANONICAL_BY_SPELLING[normalize(field)];
+	return canonical ? CARD_READERS[canonical](card) : null;
+}
+
+/**
+ * bw stores the month as the digit it was entered as ("3"), which is not what a
+ * `MM` field or an expiry string wants. Padding here means every consumer gets
+ * the two-digit form rather than each one remembering to pad.
+ */
+function readExpMonth(card: BwCard): string | null {
+	return text(card.expMonth)?.padStart(2, "0") ?? null;
+}
+
+/**
+ * Composed rather than stored: Bitwarden keeps month and year apart, and a
+ * caller filling one expiry box should not have to join them itself. The year
+ * is passed through as stored, so a vault holding `30` yields `03/30`.
+ */
+function readExpiry(card: BwCard): string | null {
+	const month = readExpMonth(card);
+	const year = text(card.expYear);
+	// Half an expiry is worse than none — it would read as a complete date.
+	return month && year ? `${month}/${year}` : null;
+}
+
+/**
+ * Normalizes a stored value to a non-empty string. Months and years arrive as
+ * either strings or numbers depending on how the item was created, and an empty
+ * string means "not set" just as much as `null` does.
+ */
+function text(value: string | number | null | undefined): string | null {
+	if (value === null || value === undefined) return null;
+	const trimmed = String(value).trim();
+	return trimmed === "" ? null : trimmed;
+}

package/src/bw/fields.ts

@@ -1,6 +1,7 @@
 import pc from "picocolors";
 import { CliError, ExitCode } from "../cli/errors.ts";
 import type { GlobalOptions } from "../cli/types.ts";
+import { isCardField, readCardValue, CARD_FIELDS } from "./cards.ts";
 import { summarizeItem, type ItemSummary } from "./items.ts";
 import { runBwOrThrow } from "./runner.ts";
 import { withSession } from "./session.ts";
@@ -12,10 +13,10 @@ import {
 	TotpUnsupportedError,
 	type TotpCode,
 } from "./totp.ts";
-import { BwItemSchema, type BwItem } from "./types.ts";
+import { BwItemSchema, BwItemType, itemTypeLabel, type BwItem } from "./types.ts";
 
-/** Fields `bw get` resolves natively; anything else is a custom field name. */
-const BUILTIN_FIELDS = [
+/** Fields `bw get` resolves natively; anything else is a card or custom field. */
+export const BUILTIN_FIELDS = [
 	"password",
 	"username",
 	"totp",
@@ -67,27 +68,49 @@ export async function readItemField(
 ): Promise<string> {
 	return withLookupHelp(item, opts, async () => {
 		if (isTotpField(field, options)) {
-			return (await resolveTotp(await fetchItem(item, opts), item, opts)).code;
+			const nextCode = resolveTotpSource(await fetchItem(item, opts), item, opts);
+			return (await nextCode()).code;
 		}
 
-		return isBuiltinField(field) && !options?.customOnly
+		if (options?.customOnly) return readCustomField(field, item, opts);
+
+		// `bw get` has no card fields, so they are read from the item itself —
+		// which also settles whether this item is a card at all.
+		if (isCardField(field)) {
+			return extractField(await fetchItem(item, opts), field, options);
+		}
+
+		return isBuiltinField(field)
 			? readBuiltinField(field, item, opts)
 			: readCustomField(field, item, opts);
 	});
 }
 
+export interface ReadTotpOptions {
+	/**
+	 * Wait for the next window when the code has fewer than this many seconds
+	 * left, rather than handing back one that expires on the way to the prompt.
+	 */
+	minSecondsRemaining?: number;
+	/** Notified with the seconds about to be spent waiting, for progress output. */
+	onWait?: (seconds: number) => void;
+}
+
 /**
  * Reads a TOTP with the time it has left. A code handed over with three seconds
- * on it is usually dead before it is pasted, so callers need the remainder to
- * decide whether to wait for the next window.
+ * on it is usually dead before it is pasted, so callers get the remainder to
+ * decide for themselves — or set `minSecondsRemaining` and have the wait handled
+ * here, where the secret is still in hand and a fresh code is free.
  */
 export async function readTotp(
 	item: string,
 	opts: GlobalOptions,
+	options?: ReadTotpOptions,
 ): Promise<TotpCode> {
-	return withLookupHelp(item, opts, async () =>
-		resolveTotp(await fetchItem(item, opts), item, opts),
-	);
+	return withLookupHelp(item, opts, async () => {
+		const nextCode = resolveTotpSource(await fetchItem(item, opts), item, opts);
+		return awaitUsableWindow(nextCode, options);
+	});
 }
 
 /** The stored secret itself, for moving a seed back out to another authenticator. */
@@ -113,29 +136,58 @@ function requireStoredTotp(item: BwItem): string {
 }
 
 /**
- * Computes the code from the secret already in hand, falling back to `bw get
- * totp` for the shapes this codebase will not compute itself (see `totp.ts`).
- * The fallback costs a second spawn, which is the correct trade against
- * emitting a confidently wrong six digits.
+ * Produces a code for the current window. Callable rather than a single resolved
+ * value so waiting out a nearly-dead window is cheap: the local path just runs
+ * the HMAC again over the secret it captured.
  */
-async function resolveTotp(
+type TotpSource = () => Promise<TotpCode>;
+
+/**
+ * Decides how this item's codes are computed: locally from the secret already in
+ * hand, or by `bw get totp` for the shapes this codebase will not compute itself
+ * (see `totp.ts`). The fallback costs a spawn per code, which is the correct
+ * trade against emitting a confidently wrong six digits.
+ */
+function resolveTotpSource(
 	fetched: BwItem,
 	item: string,
 	opts: GlobalOptions,
-): Promise<TotpCode> {
+): TotpSource {
 	const stored = requireStoredTotp(fetched);
 
 	try {
-		return generateTotp(parseTotpSecret(stored));
+		const config = parseTotpSecret(stored);
+		return async () => generateTotp(config);
 	} catch (err) {
 		if (!(err instanceof TotpUnsupportedError)) throw err;
-
-		return {
-			code: await readBuiltinField("totp", item, opts),
-			period: DEFAULT_PERIOD,
-			secondsRemaining: secondsRemaining(DEFAULT_PERIOD),
-		};
 	}
+
+	return async () => ({
+		code: await readBuiltinField("totp", item, opts),
+		period: DEFAULT_PERIOD,
+		secondsRemaining: secondsRemaining(DEFAULT_PERIOD),
+	});
+}
+
+/**
+ * Sleeps out a window with too little left, then asks the source for the next
+ * code. Only the `bw` fallback pays a second spawn for that; the local path
+ * recomputes from the secret it holds, so the returned code has a full window
+ * rather than one already spent on a second vault round-trip.
+ */
+async function awaitUsableWindow(
+	nextCode: TotpSource,
+	options?: ReadTotpOptions,
+): Promise<TotpCode> {
+	const code = await nextCode();
+
+	const minimum = options?.minSecondsRemaining;
+	if (minimum === undefined || code.secondsRemaining >= minimum) return code;
+
+	options?.onWait?.(code.secondsRemaining);
+	// The extra beat lands just past the boundary rather than exactly on it.
+	await Bun.sleep(code.secondsRemaining * 1000 + 250);
+	return nextCode();
 }
 
 /**
@@ -169,10 +221,8 @@ export async function readFields(
 			const request = requests[index]!;
 
 			if (isTotpField(request.field, request.options)) {
-				const totp = await withLookupHelp(item, opts, () =>
-					resolveTotp(fetched, item, opts),
-				);
-				values[index] = totp.code;
+				const nextCode = resolveTotpSource(fetched, item, opts);
+				values[index] = (await withLookupHelp(item, opts, nextCode)).code;
 			} else {
 				values[index] = extractField(fetched, request.field, request.options);
 			}
@@ -225,7 +275,19 @@ function extractField(
 	field: string,
 	options?: ReadFieldOptions,
 ): string {
-	if (!isBuiltinField(field) || options?.customOnly) {
+	if (options?.customOnly) return pickCustomField(item, field);
+
+	// A card field only means the card object on a card item. On anything else
+	// `number` or `code` is just a custom field name, and stealing it here would
+	// break lookups that worked before cards were understood at all — so the
+	// name is resolved as one, and the miss says what the item actually is.
+	if (isCardField(field)) {
+		return item.type === BwItemType.Card
+			? extractCardField(item, field)
+			: pickCustomField(item, field, cardFieldHint(item, field));
+	}
+
+	if (!isBuiltinField(field)) {
 		return pickCustomField(item, field);
 	}
 
@@ -233,7 +295,7 @@ function extractField(
 
 	// Named exhaustively rather than defaulted: a chain ending in `password`
 	// would hand back the password for any field it failed to recognize.
-	let value: string | null;
+	let value: string | null | undefined;
 	switch (field) {
 		case "notes":
 			value = item.notes;
@@ -291,16 +353,35 @@ async function readCustomField(
 	return pickCustomField(await fetchItem(item, opts), fieldName);
 }
 
-function pickCustomField(item: BwItem, fieldName: string): string {
+function extractCardField(item: BwItem, field: string): string {
+	const value = item.card ? readCardValue(item.card, field) : null;
+	if (!value) {
+		throw new FieldMissingError(
+			`No ${field} found for item: ${item.name}`,
+			ExitCode.NotFound,
+		);
+	}
+
+	return value;
+}
+
+/** Why a card field found nothing on an item that is not a card. */
+function cardFieldHint(item: BwItem, field: string): string {
+	return `Note: "${field}" reads a card field on card items, but "${item.name}" is a ${itemTypeLabel(item.type)} item. Card fields: ${CARD_FIELDS.join(", ")}.`;
+}
+
+/** `hint` is appended to a miss, for a name that could have meant something else. */
+function pickCustomField(item: BwItem, fieldName: string, hint?: string): string {
 	const fields = item.fields ?? [];
 	const match = fields.find((f) => f.name === fieldName);
 
 	if (!match) {
 		const available = fields.map((f) => f.name).join(", ");
+		const miss = available
+			? `Field "${fieldName}" not found. Available: ${available}`
+			: `Field "${fieldName}" not found (item has no custom fields)`;
 		throw new FieldMissingError(
-			available
-				? `Field "${fieldName}" not found. Available: ${available}`
-				: `Field "${fieldName}" not found (item has no custom fields)`,
+			hint ? `${miss}\n\n${hint}` : miss,
 			ExitCode.NotFound,
 		);
 	}

package/src/bw/items.ts

@@ -1,4 +1,4 @@
-import { BW_TYPE_LABELS } from "./types.ts";
+import { itemTypeLabel } from "./types.ts";
 
 /**
  * The only shape of a vault item bwx prints when the caller did not ask for a
@@ -25,7 +25,7 @@ export function summarizeItem(item: Record<string, unknown>): ItemSummary {
 
 	return {
 		id: String(item.id ?? ""),
-		type: BW_TYPE_LABELS[item.type as number] ?? `type:${item.type}`,
+		type: itemTypeLabel(item.type as number),
 		name: String(item.name ?? ""),
 		username: typeof username === "string" && username ? username : null,
 		hasTotp: typeof totp === "string" && totp.length > 0,

package/src/bw/session.ts

@@ -119,9 +119,11 @@ export async function ensureUnlocked(opts: GlobalOptions): Promise<void> {
 		},
 		async () => {
 			// A process that waited must use the winner's disk cache, not the stale
-			// token it may still have held in memory before entering the lock.
+			// token it may still have held in memory before entering the lock. An
+			// unchanged cache needs no second `bw status`: we just watched that exact
+			// token be refused, and nothing has replaced it.
 			const winner = loadCachedSession(opts);
-			if (winner) {
+			if (winner && winner !== cached) {
 				setSession(winner);
 				if (await sessionWorks(winner)) return;
 				setSession(null);

package/src/bw/totp.ts

@@ -81,6 +81,12 @@ export function parseTotpSecret(raw: string): TotpConfig {
 		throw new TotpUnsupportedError("secret is not base32");
 	}
 
+	// A returned config must be computable, so that generateTotp cannot fail on
+	// one and strand a caller that has already chosen the local path over the bw
+	// fallback. Base32 alone does not promise that: a single character carries
+	// five bits and decodes to no whole byte.
+	base32Decode(config.secret);
+
 	return config;
 }
 

package/src/bw/types.ts

@@ -30,6 +30,11 @@ export const BW_TYPE_LABELS: Record<number, string> = {
 	4: "identity",
 };
 
+/** The label for an item type, naming the raw number for one bwx predates. */
+export function itemTypeLabel(type: number): string {
+	return BW_TYPE_LABELS[type] ?? `type:${type}`;
+}
+
 export const BW_TYPE_FROM_NAME: Record<string, BwItemType> = {
 	login: BwItemType.Login,
 	logins: BwItemType.Login,
@@ -73,17 +78,43 @@ export interface BwLogin {
 	uris: BwUri[] | null;
 }
 
+// --- Card ---
+
+/**
+ * Values arrive as strings from `bw`, but `expMonth`/`expYear` are numbers in
+ * some hand-written and imported items, so both are accepted rather than
+ * failing the whole item parse over a field the caller may not even want. Every
+ * key is optional for the same reason — see the schema below.
+ */
+export interface BwCard {
+	cardholderName?: string | null;
+	brand?: string | null;
+	number?: string | null;
+	expMonth?: string | number | null;
+	expYear?: string | number | null;
+	code?: string | null;
+}
+
 // --- Item (loose schema — passthrough for edit round-trip) ---
 
+/**
+ * `bw get item` omits keys it has no value for rather than nulling them — an
+ * unfiled card has no `folderId`, a login without 2FA no `totp` — so every key
+ * but an item's identity is optional as well as nullable. Requiring them made
+ * an absent key fail the parse and took down reads of the fields that were
+ * present.
+ */
+const OmittableTextSchema = z.string().nullable().optional();
+
 export const BwItemSchema = z
 	.object({
 		id: z.string(),
-		organizationId: z.string().nullable(),
-		folderId: z.string().nullable(),
+		organizationId: OmittableTextSchema,
+		folderId: OmittableTextSchema,
 		type: z.number(),
 		name: z.string(),
-		notes: z.string().nullable(),
-		favorite: z.boolean(),
+		notes: OmittableTextSchema,
+		favorite: z.boolean().optional(),
 		fields: z
 			.array(
 				z.object({
@@ -92,12 +123,13 @@ export const BwItemSchema = z
 					type: z.number(),
 				}),
 			)
-			.nullable(),
+			.nullable()
+			.optional(),
 		login: z
 			.object({
-				username: z.string().nullable(),
-				password: z.string().nullable(),
-				totp: z.string().nullable(),
+				username: OmittableTextSchema,
+				password: OmittableTextSchema,
+				totp: OmittableTextSchema,
 				uris: z
 					.array(
 						z.object({
@@ -105,8 +137,23 @@ export const BwItemSchema = z
 							uri: z.string(),
 						}),
 					)
-					.nullable(),
+					.nullable()
+					.optional(),
+			})
+			.passthrough()
+			.nullable()
+			.optional(),
+		card: z
+			.object({
+				cardholderName: OmittableTextSchema,
+				brand: OmittableTextSchema,
+				number: OmittableTextSchema,
+				// Numeric in items written by hand or by an importer.
+				expMonth: z.union([z.string(), z.number()]).nullable().optional(),
+				expYear: z.union([z.string(), z.number()]).nullable().optional(),
+				code: OmittableTextSchema,
 			})
+			.passthrough()
 			.nullable()
 			.optional(),
 		reprompt: z.number().optional(),

package/src/cli/commands/create.ts

@@ -11,7 +11,9 @@ import {
 	assertSingleStdinSource,
 	collect,
 	listExplicitStdinInputs,
+	loginOnlyTextInputFlags,
 	readOptionalStdin,
+	registerItemTextOptions,
 	resolveFieldSources,
 	resolveItemTextInputs,
 	StdinReader,
@@ -36,36 +38,18 @@ interface CreateOptions extends ItemTextInputs {
 /** Flags a secure note has nowhere to store — see {@link assertLoginFlags}. */
 const LOGIN_ONLY_FLAGS: Array<[keyof CreateOptions, string]> = [
 	["username", "--username"],
-	["password", "--password"],
-	["passwordStdin", "--password-stdin"],
-	["passwordFile", "--password-file"],
-	["passwordEnv", "--password-env"],
-	["passwordGenerate", "--password-generate"],
-	["totp", "--totp"],
-	["totpStdin", "--totp-stdin"],
-	["totpFile", "--totp-file"],
-	["totpEnv", "--totp-env"],
+	...loginOnlyTextInputFlags(),
 ];
 
 export function registerCreate(program: Command): void {
-	program
+	const command = program
 		.command("create").alias("add")
 		.description("Create a new vault item")
 		.option("--type <type>", "Item type: login|note", "note")
 		.option("--name <name>", "Item name")
-		.option("--notes <text>", "Notes content")
-		.option("--notes-file <path>", "Read notes from file (use - for stdin)")
-		.option("--username <user>", "Username (login type)")
-		.option("--password <pass>", "Password (login type)")
-		.option("--password-stdin", "Read password from stdin")
-		.option("--password-file <path>", "Read password from file (use - for stdin)")
-		.option("--password-env <name>", "Read password from environment variable")
-		.option("--password-generate", "Generate the password; it is never printed")
-		.option("--generate-length <n>", "Length for --password-generate", parseInt)
-		.option("--totp <secret>", "TOTP secret: base32 or otpauth:// URI (login type)")
-		.option("--totp-stdin", "Read the TOTP secret from stdin")
-		.option("--totp-file <path>", "Read the TOTP secret from file (use - for stdin)")
-		.option("--totp-env <name>", "Read the TOTP secret from environment variable")
+		.option("--username <user>", "Username (login items only)");
+
+	registerItemTextOptions(command)
 		.option("--uri <url>", "URI (repeatable)", collect, [])
 		.option("--field <kv>", "Custom field k=v (repeatable)", collect, [])
 		.option("--field-file <kv>", "Custom field value from file k=path (repeatable)", collect, [])

package/src/cli/commands/edit.ts

@@ -12,9 +12,13 @@ import {
 	assertSingleStdinSource,
 	collect,
 	listExplicitStdinInputs,
+	listUsedSourceFlags,
+	loginOnlyTextInputFlags,
+	registerItemTextOptions,
 	resolveFieldSources,
 	resolveItemTextInputs,
 	StdinReader,
+	TOTP_FAMILY,
 	type ItemTextInputs,
 } from "../input.ts";
 import { redactGeneratedPassword } from "./generate.ts";
@@ -36,37 +40,19 @@ interface EditOptions extends ItemTextInputs {
 
 const LOGIN_ONLY_FLAGS: Array<[keyof EditOptions, string]> = [
 	["username", "--username"],
-	["password", "--password"],
-	["passwordStdin", "--password-stdin"],
-	["passwordFile", "--password-file"],
-	["passwordEnv", "--password-env"],
-	["passwordGenerate", "--password-generate"],
-	["totp", "--totp"],
-	["totpStdin", "--totp-stdin"],
-	["totpFile", "--totp-file"],
-	["totpEnv", "--totp-env"],
+	...loginOnlyTextInputFlags(),
 	["rmTotp", "--rm-totp"],
 ];
 
 export function registerEdit(program: Command): void {
-	program
+	const command = program
 		.command("edit")
 		.description("Edit an existing vault item")
 		.argument("<item>", "Item name or ID")
 		.option("--name <name>", "New name")
-		.option("--notes <text>", "New notes")
-		.option("--notes-file <path>", "Read notes from file (use - for stdin)")
-		.option("--username <user>", "New username")
-		.option("--password <pass>", "New password")
-		.option("--password-stdin", "Read password from stdin")
-		.option("--password-file <path>", "Read password from file (use - for stdin)")
-		.option("--password-env <name>", "Read password from environment variable")
-		.option("--password-generate", "Generate the password; it is never printed")
-		.option("--generate-length <n>", "Length for --password-generate", parseInt)
-		.option("--totp <secret>", "Set TOTP secret: base32 or otpauth:// URI")
-		.option("--totp-stdin", "Read the TOTP secret from stdin")
-		.option("--totp-file <path>", "Read the TOTP secret from file (use - for stdin)")
-		.option("--totp-env <name>", "Read the TOTP secret from environment variable")
+		.option("--username <user>", "New username");
+
+	registerItemTextOptions(command)
 		.option("--rm-totp", "Remove the stored TOTP secret")
 		.option("--uri <url>", "Set URIs (repeatable, replaces all)", collect, [])
 		.option("--add-field <kv>", "Add/update field k=v", collect, [])
@@ -165,12 +151,7 @@ export function registerEdit(program: Command): void {
 function assertTotpIntent(localOpts: EditOptions): void {
 	if (!localOpts.rmTotp) return;
 
-	const setters = [
-		localOpts.totp !== undefined ? "--totp" : null,
-		localOpts.totpStdin ? "--totp-stdin" : null,
-		localOpts.totpFile !== undefined ? "--totp-file" : null,
-		localOpts.totpEnv !== undefined ? "--totp-env" : null,
-	].filter((flag): flag is string => flag !== null);
+	const setters = listUsedSourceFlags(TOTP_FAMILY, localOpts);
 
 	if (setters.length > 0) {
 		throw new CliError(

package/src/cli/commands/get.ts

@@ -1,7 +1,8 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { emitData, emitLog } from "../io.ts";
-import { readItemField, readTotp, readTotpSecret } from "../../bw/fields.ts";
+import { BUILTIN_FIELDS, readItemField, readTotp, readTotpSecret } from "../../bw/fields.ts";
+import { CARD_FIELDS } from "../../bw/cards.ts";
 import { CliError, ExitCode } from "../errors.ts";
 import type { GlobalOptions } from "../types.ts";
 
@@ -12,7 +13,10 @@ export function registerGet(program: Command): void {
 	program
 		.command("get")
 		.description("Get a field from a vault item (built-in or custom)")
-		.argument("<field>", "Field: password | username | totp | notes | uri | item | <custom>")
+		.argument(
+			"<field>",
+			`Field: ${BUILTIN_FIELDS.join(" | ")} | <custom>. Card items also take: ${CARD_FIELDS.join(" | ")}`,
+		)
 		.argument("<item>", "Item name or ID")
 		.option(
 			"--fresh [seconds]",
@@ -80,15 +84,11 @@ async function emitTotp(
 		return;
 	}
 
-	const threshold = parseFreshSeconds(localOpts.fresh);
-	let totp = await readTotp(item, opts);
-
-	if (threshold !== null && totp.secondsRemaining < threshold) {
-		const wait = totp.secondsRemaining;
-		emitLog(`Waiting ${wait}s for a fresh code…`, opts);
-		await Bun.sleep(wait * 1000 + 250);
-		totp = await readTotp(item, opts);
-	}
+	const totp = await readTotp(item, opts, {
+		minSecondsRemaining: parseFreshSeconds(localOpts.fresh),
+		onWait: (seconds) =>
+			emitLog(`Waiting ${seconds}s for a fresh code…`, opts),
+	});
 
 	emitLog(`Valid for ${totp.secondsRemaining}s`, opts);
 	emitData(totp.code, opts, {
@@ -101,8 +101,8 @@ async function emitTotp(
  * `--fresh` is a bare flag by default and takes an explicit threshold when the
  * caller needs longer than {@link DEFAULT_FRESH_SECONDS} to use the code.
  */
-function parseFreshSeconds(raw: string | boolean | undefined): number | null {
-	if (raw === undefined || raw === false) return null;
+function parseFreshSeconds(raw: string | boolean | undefined): number | undefined {
+	if (raw === undefined || raw === false) return undefined;
 	if (raw === true) return DEFAULT_FRESH_SECONDS;
 
 	const value = Number(raw.trim());

package/src/cli/commands/run.ts

@@ -70,7 +70,8 @@ export function parseEnvSpecs(raws: string[]): EnvSpec[] {
 /**
  * Splits `NAME=<field>:<item>` on the first `=` and then the first `:`, so item
  * names may contain colons (`password:http://my.router`) while field names may not.
- * Fields resolve exactly as in `bwx get`: built-ins first, otherwise custom fields.
+ * Fields resolve exactly as in `bwx get`: built-ins first, then card fields on a card
+ * item, otherwise custom fields.
  */
 export function parseEnvSpec(raw: string): EnvSpec {
 	const eq = raw.indexOf("=");

package/src/cli/input.ts

@@ -1,3 +1,4 @@
+import type { Command } from "commander";
 import { parseFieldFlag, type ParsedField } from "../bw/encoding.ts";
 import { normalizeTotpInput } from "../bw/totp.ts";
 import { CliError, ExitCode } from "./errors.ts";
@@ -80,15 +81,176 @@ export interface ExplicitStdinInputs extends ItemTextInputs {
 	fieldFiles?: string[];
 }
 
-const NOTE_SOURCE_FLAGS = ["--notes", "--notes-file"];
-const PASSWORD_SOURCE_FLAGS = [
-	"--password",
-	"--password-stdin",
-	"--password-file",
-	"--password-env",
-	"--password-generate",
-];
-const TOTP_SOURCE_FLAGS = ["--totp", "--totp-stdin", "--totp-file", "--totp-env"];
+/** Which slot of a {@link TextSource} a flag fills. */
+type TextSourceKind = "inline" | "stdin" | "file" | "env" | "generate";
+
+interface TextInputFlag {
+	/** Commander option spec, e.g. `--password-file <path>`. */
+	spec: string;
+	description: string;
+	/** The property commander derives from `spec`. */
+	key: keyof ItemTextInputs;
+	kind: TextSourceKind;
+}
+
+/**
+ * One value a caller can supply, and every flag that can supply it. Option
+ * registration, the "choose only one source" error, the stdin-conflict check and
+ * the login-only guard all read from here, so adding a source touches one table
+ * rather than both write commands and three hand-kept lists.
+ */
+export interface TextInputFamily {
+	/** Names the value in error messages. */
+	label: string;
+	flags: TextInputFlag[];
+	/** True when only a login item has anywhere to store the value. */
+	loginOnly: boolean;
+	/** Whether empty is a legitimate value — it is, for notes. */
+	allowEmpty?: boolean;
+}
+
+const NOTES_FAMILY: TextInputFamily = {
+	label: "notes",
+	loginOnly: false,
+	allowEmpty: true,
+	flags: [
+		{
+			spec: "--notes <text>",
+			description: "Notes content",
+			key: "notes",
+			kind: "inline",
+		},
+		{
+			spec: "--notes-file <path>",
+			description: "Read notes from file (use - for stdin)",
+			key: "notesFile",
+			kind: "file",
+		},
+	],
+};
+
+const PASSWORD_FAMILY: TextInputFamily = {
+	label: "password",
+	loginOnly: true,
+	flags: [
+		{
+			spec: "--password <pass>",
+			description: "Password (login items only)",
+			key: "password",
+			kind: "inline",
+		},
+		{
+			spec: "--password-stdin",
+			description: "Read password from stdin",
+			key: "passwordStdin",
+			kind: "stdin",
+		},
+		{
+			spec: "--password-file <path>",
+			description: "Read password from file (use - for stdin)",
+			key: "passwordFile",
+			kind: "file",
+		},
+		{
+			spec: "--password-env <name>",
+			description: "Read password from environment variable",
+			key: "passwordEnv",
+			kind: "env",
+		},
+		{
+			spec: "--password-generate",
+			description: "Generate the password; it is never printed",
+			key: "passwordGenerate",
+			kind: "generate",
+		},
+	],
+};
+
+export const TOTP_FAMILY: TextInputFamily = {
+	label: "TOTP secret",
+	loginOnly: true,
+	flags: [
+		{
+			spec: "--totp <secret>",
+			description: "TOTP secret: base32 or otpauth:// URI (login items only)",
+			key: "totp",
+			kind: "inline",
+		},
+		{
+			spec: "--totp-stdin",
+			description: "Read the TOTP secret from stdin",
+			key: "totpStdin",
+			kind: "stdin",
+		},
+		{
+			spec: "--totp-file <path>",
+			description: "Read the TOTP secret from file (use - for stdin)",
+			key: "totpFile",
+			kind: "file",
+		},
+		{
+			spec: "--totp-env <name>",
+			description: "Read the TOTP secret from environment variable",
+			key: "totpEnv",
+			kind: "env",
+		},
+	],
+};
+
+const ITEM_TEXT_FAMILIES = [NOTES_FAMILY, PASSWORD_FAMILY, TOTP_FAMILY];
+
+function flagName(spec: string): string {
+	return spec.split(" ")[0]!;
+}
+
+function sourceFlagNames(family: TextInputFamily): string[] {
+	return family.flags.map((flag) => flagName(flag.spec));
+}
+
+/**
+ * Registers every flag that can supply notes, a password, or a TOTP secret, plus
+ * the length modifier `--password-generate` takes. `create` and `edit` accept the
+ * identical set and {@link resolveItemTextInputs} is their only reader, so the
+ * set is declared once here instead of per command.
+ */
+export function registerItemTextOptions(command: Command): Command {
+	for (const family of ITEM_TEXT_FAMILIES) {
+		for (const flag of family.flags) {
+			command.option(flag.spec, flag.description);
+		}
+	}
+
+	return command.option(
+		"--generate-length <n>",
+		"Length for --password-generate",
+		(value) => Number.parseInt(value, 10),
+	);
+}
+
+/**
+ * The `[key, flag]` pairs a command must reject on a non-login item, because
+ * `buildNewItem` and `patchItem` have nowhere to put them and would accept the
+ * value only to drop it.
+ */
+export function loginOnlyTextInputFlags(): Array<[keyof ItemTextInputs, string]> {
+	return ITEM_TEXT_FAMILIES.filter((family) => family.loginOnly).flatMap(
+		(family) =>
+			family.flags.map(
+				(flag) =>
+					[flag.key, flagName(flag.spec)] as [keyof ItemTextInputs, string],
+			),
+	);
+}
+
+/** The flags a caller actually used to supply this family's value. */
+export function listUsedSourceFlags(
+	family: TextInputFamily,
+	inputs: ItemTextInputs,
+): string[] {
+	return family.flags
+		.filter((flag) => inputs[flag.key] !== undefined)
+		.map((flag) => flagName(flag.spec));
+}
 
 export async function resolveItemTextInputs(
 	inputs: ItemTextInputs,
@@ -100,17 +262,17 @@ export async function resolveItemTextInputs(
 	const [notes, password, totp] = await Promise.all([
 		resolveOptionalTextSource(
 			{
-				label: "notes",
+				label: NOTES_FAMILY.label,
 				inline: inputs.notes,
 				file: inputs.notesFile,
-				flagNames: NOTE_SOURCE_FLAGS,
-				allowEmpty: true,
+				flagNames: sourceFlagNames(NOTES_FAMILY),
+				allowEmpty: NOTES_FAMILY.allowEmpty,
 			},
 			stdin,
 		),
 		resolveOptionalTextSource(
 			{
-				label: "password",
+				label: PASSWORD_FAMILY.label,
 				inline: inputs.password,
 				stdin: inputs.passwordStdin,
 				file: inputs.passwordFile,
@@ -119,18 +281,18 @@ export async function resolveItemTextInputs(
 					inputs.passwordGenerate && generatePassword
 						? generatePassword
 						: undefined,
-				flagNames: PASSWORD_SOURCE_FLAGS,
+				flagNames: sourceFlagNames(PASSWORD_FAMILY),
 			},
 			stdin,
 		),
 		resolveOptionalTextSource(
 			{
-				label: "TOTP secret",
+				label: TOTP_FAMILY.label,
 				inline: inputs.totp,
 				stdin: inputs.totpStdin,
 				file: inputs.totpFile,
 				env: inputs.totpEnv,
-				flagNames: TOTP_SOURCE_FLAGS,
+				flagNames: sourceFlagNames(TOTP_FAMILY),
 			},
 			stdin,
 		),
@@ -147,16 +309,26 @@ export async function resolveItemTextInputs(
 }
 
 export function listExplicitStdinInputs(inputs: ExplicitStdinInputs): string[] {
-	return [
-		inputs.notesFile === "-" ? "--notes-file -" : null,
-		inputs.passwordStdin ? "--password-stdin" : null,
-		inputs.passwordFile === "-" ? "--password-file -" : null,
-		inputs.totpStdin ? "--totp-stdin" : null,
-		inputs.totpFile === "-" ? "--totp-file -" : null,
-		...(inputs.fieldFileFlag && inputs.fieldFiles
-			? stdinSourcesForFieldFiles(inputs.fieldFileFlag, inputs.fieldFiles)
-			: []),
-	].filter((value): value is string => value !== null);
+	const sources: string[] = [];
+
+	for (const family of ITEM_TEXT_FAMILIES) {
+		for (const flag of family.flags) {
+			const name = flagName(flag.spec);
+			if (flag.kind === "stdin" && inputs[flag.key]) {
+				sources.push(name);
+			} else if (flag.kind === "file" && inputs[flag.key] === "-") {
+				sources.push(`${name} -`);
+			}
+		}
+	}
+
+	if (inputs.fieldFileFlag && inputs.fieldFiles) {
+		sources.push(
+			...stdinSourcesForFieldFiles(inputs.fieldFileFlag, inputs.fieldFiles),
+		);
+	}
+
+	return sources;
 }
 
 export async function resolveOptionalTextSource(

package/src/config/process-lock.ts

@@ -64,32 +64,42 @@ export async function withProcessLock<T>(
 
 async function acquire(options: ProcessLockOptions): Promise<Ownership> {
 	const startedAt = performance.now();
-	let holder: LockOwner | null = null;
 
 	while (true) {
 		const ownership = tryCreate(options.path);
 		if (ownership) return ownership;
 
-		holder = readOwner(options.path, options.label);
-		if (!holder) continue;
+		const holder = readOwner(options.path, options.label);
 
-		if (!isProcessAlive(holder.pid)) {
+		if (holder && !isProcessAlive(holder.pid)) {
 			if (detachAbandonedLock(options.path, holder, options.label)) continue;
 		}
 
+		// The deadline is checked even when the lock turned out to be free, so a
+		// peer that keeps taking and releasing it cannot spin us indefinitely.
 		const elapsed = performance.now() - startedAt;
-		if (elapsed >= options.waitMs) {
-			throw new CliError(
-				`Timed out after ${formatDuration(options.waitMs)} waiting for ${options.label} held by pid ${holder.pid}`,
-				ExitCode.Timeout,
-			);
-		}
+		if (elapsed >= options.waitMs) throw timedOut(options, holder);
+
+		// A lock that vanished mid-inspection is free: contend for it again at once
+		// rather than sleeping on a holder that is already gone.
+		if (!holder) continue;
 
 		const remaining = options.waitMs - elapsed;
 		await Bun.sleep(Math.min(options.pollMs ?? DEFAULT_POLL_MS, remaining));
 	}
 }
 
+function timedOut(
+	options: ProcessLockOptions,
+	holder: LockOwner | null,
+): CliError {
+	const held = holder ? ` held by pid ${holder.pid}` : "";
+	return new CliError(
+		`Timed out after ${formatDuration(options.waitMs)} waiting for ${options.label}${held}`,
+		ExitCode.Timeout,
+	);
+}
+
 function tryCreate(path: string): Ownership | null {
 	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
 
@@ -143,6 +153,14 @@ function readOwner(path: string, label: string): LockOwner | null {
 
 	const read = readPrivateFile(`${path}/${OWNER_FILE}`);
 	if (read.kind !== "ok") {
+		// A holder publishes `owner.json` before the directory is renamed into
+		// place, and lets go by renaming the whole directory away. So an owner file
+		// that would not read, under a directory that is no longer the one just
+		// inspected, means the holder released mid-read — the caller should contend
+		// again rather than report a corrupt lock. Only an unreadable owner file in
+		// the *same* directory is genuinely wrong.
+		if (inodeAt(path) !== stat.ino) return null;
+
 		const reason =
 			read.kind === "missing"
 				? `${path}/${OWNER_FILE} is missing`
@@ -246,6 +264,20 @@ function pathExists(path: string): boolean {
 	}
 }
 
+/**
+ * Identifies what currently sits at `path`, or `null` when nothing does. Compared
+ * against an earlier `stat` it answers "is this still the same directory?", which
+ * distinguishes a released lock from a corrupt one.
+ */
+function inodeAt(path: string): number | null {
+	try {
+		return lstatSync(path).ino;
+	} catch (err) {
+		if (errorCode(err) === "ENOENT") return null;
+		throw err;
+	}
+}
+
 function errorCode(err: unknown): string | undefined {
 	return (err as NodeJS.ErrnoException)?.code;
 }