bwx 0.6.3 → 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.3",
+  "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",
@@ -71,7 +72,15 @@ export async function readItemField(
 			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);
 	});
@@ -266,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);
 	}
 
@@ -274,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;
@@ -332,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/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/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]",

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("=");