bwx 0.8.0 → 0.10.0

package/src/bw/encoding.ts

@@ -1,4 +1,4 @@
-import type { BwField, BwFieldType, BwItem, BwItemType, BwUri } from "./types.ts";
+import type { BwCard, BwField, BwFieldType, BwItem, BwItemType, BwUri } from "./types.ts";
 import { BwFieldType as FT, BwItemType as IT } from "./types.ts";
 
 // --- Field flag parsing ---
@@ -35,21 +35,27 @@ export function parseFieldFlag(raw: string): ParsedField {
 // --- Build new item JSON ---
 
 export interface NewItemOptions {
-	type?: "login" | "note";
+	type?: "login" | "note" | "card";
 	name: string;
 	notes?: string | null;
 	username?: string | null;
 	password?: string | null;
 	totp?: string | null;
 	uris?: string[];
+	card?: BwCard;
 	fields?: ParsedField[];
 	folderId?: string | null;
 	favorite?: boolean;
 }
 
+const ITEM_TYPE_BY_NAME = {
+	login: IT.Login,
+	note: IT.SecureNote,
+	card: IT.Card,
+} as const;
+
 export function buildNewItem(options: NewItemOptions): Record<string, unknown> {
-	const isLogin = options.type === "login";
-	const itemType: BwItemType = isLogin ? IT.Login : IT.SecureNote;
+	const itemType: BwItemType = ITEM_TYPE_BY_NAME[options.type ?? "note"];
 
 	const item: Record<string, unknown> = {
 		organizationId: null,
@@ -62,7 +68,7 @@ export function buildNewItem(options: NewItemOptions): Record<string, unknown> {
 		reprompt: 0,
 	};
 
-	if (isLogin) {
+	if (itemType === IT.Login) {
 		item.login = {
 			username: options.username ?? null,
 			password: options.password ?? null,
@@ -71,6 +77,17 @@ export function buildNewItem(options: NewItemOptions): Record<string, unknown> {
 				? options.uris.map((uri) => ({ match: null, uri }))
 				: null,
 		};
+	} else if (itemType === IT.Card) {
+		item.card = {
+			cardholderName: null,
+			brand: null,
+			number: null,
+			expMonth: null,
+			expYear: null,
+			code: null,
+			...options.card,
+		};
+		item.login = null;
 	} else {
 		item.secureNote = { type: 0 };
 		item.login = null;
@@ -99,6 +116,8 @@ export interface PatchOptions {
 	/** `null` clears the stored secret; `undefined` leaves it alone. */
 	totp?: string | null;
 	uris?: string[];
+	/** Each key: a value sets it, `null` clears it, absent leaves it alone. */
+	card?: BwCard;
 	addFields?: ParsedField[];
 	rmFields?: string[];
 	/** `null` unfiles the item; `undefined` leaves its folder alone. */
@@ -136,6 +155,14 @@ export function patchItem(
 		result.login = login;
 	}
 
+	if (patch.card && Object.keys(patch.card).length > 0) {
+		// Copied for the same reason as `login` above.
+		result.card = {
+			...((result.card as Record<string, unknown>) ?? {}),
+			...patch.card,
+		};
+	}
+
 	// Fields: remove then add
 	let fields = Array.isArray(result.fields) ? [...(result.fields as BwField[])] : [];
 	if (patch.rmFields?.length) {

package/src/bw/fields.ts

@@ -4,6 +4,7 @@ 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 { withSafeVaultErrors } from "./safe-errors.ts";
 import { withSession } from "./session.ts";
 import {
 	DEFAULT_PERIOD,
@@ -13,7 +14,9 @@ import {
 	TotpUnsupportedError,
 	type TotpCode,
 } from "./totp.ts";
-import { BwItemSchema, BwItemType, itemTypeLabel, type BwItem } from "./types.ts";
+import {
+	BwItemSchema, BwItemType, customFieldTypeLabel, itemTypeLabel, type BwItem,
+} from "./types.ts";
 
 /** Fields `bw get` resolves natively; anything else is a card or custom field. */
 export const BUILTIN_FIELDS = [
@@ -35,6 +38,10 @@ function isTotpField(field: string, options?: ReadFieldOptions): boolean {
 }
 
 export interface ReadFieldOptions {
+	/** Reference reads require an exact ID and never print raw vault diagnostics. */
+	exactItemId?: boolean;
+	/** Position plus name identifies a custom field, including duplicate names. */
+	customIndex?: number;
 	/**
 	 * Always resolve `field` as a custom field name, so an item whose custom
 	 * field is called e.g. `password` is still reachable.
@@ -74,6 +81,16 @@ export async function readItemField(
 	opts: GlobalOptions,
 	options?: ReadFieldOptions,
 ): Promise<string> {
+	if (options?.exactItemId) {
+		return withSafeVaultErrors("Could not read field reference", async () => {
+			const values = await resolveFields([{ field, item, options }], opts);
+			const value = values[0]!;
+			if (options.verbatim || options.customOnly || isCardField(field)) return value;
+			const trimmed = value.trim();
+			if (!trimmed) throw new FieldMissingError("Field has no value", ExitCode.NotFound);
+			return trimmed;
+		});
+	}
 	return withLookupHelp(item, opts, async () => {
 		if (isTotpField(field, options)) {
 			const nextCode = resolveTotpSource(await fetchItem(item, opts), item, opts);
@@ -95,6 +112,7 @@ export async function readItemField(
 }
 
 export interface ReadTotpOptions {
+	exactItemId?: boolean;
 	/**
 	 * 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.
@@ -115,21 +133,25 @@ export async function readTotp(
 	opts: GlobalOptions,
 	options?: ReadTotpOptions,
 ): Promise<TotpCode> {
-	return withLookupHelp(item, opts, async () => {
-		const nextCode = resolveTotpSource(await fetchItem(item, opts), item, opts);
+	const read = async () => {
+		const fetched = await fetchItem(item, opts, options?.exactItemId);
+		const nextCode = resolveTotpSource(fetched, item, opts);
 		return awaitUsableWindow(nextCode, options);
-	});
+	};
+	return withFieldLookup(item, opts, options?.exactItemId, read);
 }
 
 /** The stored secret itself, for moving a seed back out to another authenticator. */
 export async function readTotpSecret(
 	item: string,
 	opts: GlobalOptions,
+	exactItemId = false,
 ): Promise<string> {
-	return withLookupHelp(item, opts, async () => {
-		const fetched = await fetchItem(item, opts);
+	const read = async () => {
+		const fetched = await fetchItem(item, opts, exactItemId);
 		return requireStoredTotp(fetched);
-	});
+	};
+	return withFieldLookup(item, opts, exactItemId, read);
 }
 
 function requireStoredTotp(item: BwItem): string {
@@ -210,6 +232,16 @@ async function awaitUsableWindow(
 export async function readFields(
 	requests: FieldRequest[],
 	opts: GlobalOptions,
+): Promise<string[]> {
+	const read = () => resolveFields(requests, opts);
+	return requests.some((request) => request.options?.exactItemId)
+		? withSafeVaultErrors("Could not read field reference", read)
+		: read();
+}
+
+async function resolveFields(
+	requests: FieldRequest[],
+	opts: GlobalOptions,
 ): Promise<string[]> {
 	const values = new Array<string>(requests.length);
 	const byItem = new Map<string, number[]>();
@@ -223,14 +255,20 @@ export async function readFields(
 	for (const [item, indexes] of byItem) {
 		// A single `bw` process at a time: each read may trigger an unlock, and
 		// concurrent unlocks would race over the cached session.
-		const fetched = await withLookupHelp(item, opts, () => fetchItem(item, opts));
+		const exact = indexes.some((index) => requests[index]!.options?.exactItemId);
+		const fetched = exact
+			? await fetchItem(item, opts, true)
+			: await withLookupHelp(item, opts, () => fetchItem(item, opts));
 
 		for (const index of indexes) {
 			const request = requests[index]!;
 
 			if (isTotpField(request.field, request.options)) {
 				const nextCode = resolveTotpSource(fetched, item, opts);
-				values[index] = (await withLookupHelp(item, opts, nextCode)).code;
+				const code = exact
+					? await nextCode()
+					: await withLookupHelp(item, opts, nextCode);
+				values[index] = code.code;
 			} else {
 				values[index] = extractField(fetched, request.field, request.options);
 			}
@@ -240,6 +278,17 @@ export async function readFields(
 	return values;
 }
 
+/** Exact references suppress raw diagnostics; named lookups retain suggestions. */
+function withFieldLookup<T>(
+	item: string,
+	opts: GlobalOptions,
+	exactItemId: boolean | undefined,
+	read: () => Promise<T>,
+): Promise<T> {
+	if (exactItemId) return withSafeVaultErrors("Could not read field reference", read);
+	return withLookupHelp(item, opts, read);
+}
+
 /**
  * Turns bw's bare "Not found." and "More than one result" into errors that name
  * the candidates, so a caller can correct itself without a round of guessing.
@@ -272,9 +321,17 @@ async function withLookupHelp<T>(
 	}
 }
 
-async function fetchItem(item: string, opts: GlobalOptions): Promise<BwItem> {
+async function fetchItem(
+	item: string,
+	opts: GlobalOptions,
+	exactItemId = false,
+): Promise<BwItem> {
 	const json = await withSession(opts, () => runBwOrThrow(["get", "item", item]));
-	return BwItemSchema.parse(JSON.parse(json));
+	const fetched = BwItemSchema.parse(JSON.parse(json));
+	if (exactItemId && fetched.id.toLowerCase() !== item.toLowerCase()) {
+		throw new CliError("Vault returned a different item ID", ExitCode.BwError);
+	}
+	return fetched;
 }
 
 /** Mirrors what `bw get <field>` would have returned for an already-fetched item. */
@@ -283,6 +340,9 @@ function extractField(
 	field: string,
 	options?: ReadFieldOptions,
 ): string {
+	if (options?.customIndex !== undefined) {
+		return pickReferencedCustomField(item, options.customIndex, field);
+	}
 	if (options?.customOnly) return pickCustomField(item, field);
 
 	// A card field only means the card object on a card item. On anything else
@@ -290,6 +350,9 @@ function extractField(
 	// 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)) {
+		if (options?.exactItemId && item.type !== BwItemType.Card) {
+			throw new FieldMissingError("No built-in card field on this item", ExitCode.NotFound);
+		}
 		return item.type === BwItemType.Card
 			? extractCardField(item, field)
 			: pickCustomField(item, field, cardFieldHint(item, field));
@@ -398,6 +461,15 @@ function pickCustomField(item: BwItem, fieldName: string, hint?: string): string
 	return match.value ?? "";
 }
 
+/** Position plus name guards a custom reference against moved or removed fields. */
+function pickReferencedCustomField(item: BwItem, index: number, name: string): string {
+	const field = item.fields?.[index];
+	if (!field || field.name !== name || customFieldTypeLabel(field.type) === undefined) {
+		throw new CliError("Custom field reference changed; discover fields again", ExitCode.BadArgs);
+	}
+	return field.value ?? "";
+}
+
 async function findMatches(query: string): Promise<ItemSummary[]> {
 	try {
 		const json = await runBwOrThrow(["list", "items", "--search", query]);

package/src/bw/items.ts

@@ -1,8 +1,7 @@
 import { itemTypeLabel } from "./types.ts";
 
 /**
- * The only shape of a vault item bwx prints when the caller did not ask for a
- * specific secret. Enough to identify an item and follow up with a narrow `get`,
+ * Default listing shape. Enough to identify an item and follow up with a narrow `get`,
  * with no room for passwords, notes, custom fields, or URIs to leak into logs.
  */
 export interface ItemSummary {

package/src/bw/references.ts

@@ -0,0 +1,58 @@
+import { CliError, ExitCode } from "../cli/errors.ts";
+import { CARD_FIELDS } from "./cards.ts";
+import type { FieldRequest } from "./fields.ts";
+
+export const REFERENCE_PREFIX = "bwx://";
+export const ITEM_ID_RE =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const REFERENCE_BUILTINS: readonly string[] = [
+	"username",
+	"password",
+	"totp",
+	"notes",
+	"uri",
+	...CARD_FIELDS,
+];
+
+export function builtinReference(id: string, field: string): string {
+	return `${REFERENCE_PREFIX}${id}/builtin/${field}`;
+}
+
+/** Index distinguishes duplicate and empty custom names; name guards against moves. */
+export function customReference(id: string, index: number, name: string): string {
+	return `${REFERENCE_PREFIX}${id}/custom/${index}/${encodeURIComponent(name)}`;
+}
+
+/** Parse directly: URL normalization would change custom names such as '.' or '..'. */
+export function parseFieldReference(ref: string): FieldRequest {
+	if (!ref.startsWith(REFERENCE_PREFIX)) throw invalidReference();
+	const [id, kind, ...parts] = ref.slice(REFERENCE_PREFIX.length).split("/");
+	if (!id || !ITEM_ID_RE.test(id)) throw invalidReference();
+	if (kind === "builtin" && parts.length === 1 && REFERENCE_BUILTINS.includes(parts[0]!)) {
+		return { item: id, field: parts[0]!, options: { exactItemId: true } };
+	}
+	if (kind !== "custom" || parts.length !== 2 || !/^(0|[1-9]\d*)$/.test(parts[0]!)) {
+		throw invalidReference();
+	}
+	const index = Number(parts[0]);
+	if (!Number.isSafeInteger(index)) throw invalidReference();
+	let name: string;
+	try {
+		name = decodeURIComponent(parts[1]!);
+	} catch {
+		throw invalidReference();
+	}
+	if (encodeURIComponent(name) !== parts[1]) throw invalidReference();
+	return {
+		item: id,
+		field: name,
+		options: { exactItemId: true, customOnly: true, customIndex: index },
+	};
+}
+
+function invalidReference(): CliError {
+	return new CliError(
+		"Invalid field reference. Copy a ref from 'bwx search <query> --fields'.",
+		ExitCode.BadArgs,
+	);
+}

package/src/bw/safe-errors.ts

@@ -0,0 +1,24 @@
+import { CliError, ExitCode } from "../cli/errors.ts";
+
+const REASONS: Partial<Record<ExitCode, string>> = {
+	[ExitCode.AuthFailed]: "authentication failed",
+	[ExitCode.NotFound]: "item or field not found",
+	[ExitCode.BadArgs]: "invalid arguments or stale reference",
+	[ExitCode.Network]: "network error",
+	[ExitCode.Timeout]: "timeout",
+	[ExitCode.Config]: "configuration error",
+};
+
+/** Vault diagnostics and parse errors can contain values. Never forward them. */
+export async function withSafeVaultErrors<T>(
+	context: string,
+	fn: () => Promise<T>,
+): Promise<T> {
+	try {
+		return await fn();
+	} catch (err) {
+		const code = err instanceof CliError ? err.exitCode : ExitCode.BwError;
+		const reason = REASONS[code] ?? "vault command or response failed";
+		throw new CliError(`${context}: ${reason}.`, code);
+	}
+}

package/src/bw/types.ts

@@ -56,6 +56,22 @@ export const BwFieldType = {
 
 export type BwFieldType = (typeof BwFieldType)[keyof typeof BwFieldType];
 
+/** Only these custom field types have a supported value reader. */
+export function customFieldTypeLabel(
+	type: number,
+): "text" | "hidden" | "boolean" | undefined {
+	switch (type) {
+		case BwFieldType.Text:
+			return "text";
+		case BwFieldType.Hidden:
+			return "hidden";
+		case BwFieldType.Boolean:
+			return "boolean";
+		default:
+			return undefined;
+	}
+}
+
 export interface BwField {
 	name: string;
 	value: string;

package/src/cli/card-options.ts

@@ -0,0 +1,169 @@
+import type { Command } from "commander";
+import type { BwCard } from "../bw/types.ts";
+import {
+	inferBrand,
+	normalizeBrand,
+	parseExpiry,
+	parseExpMonth,
+	parseExpYear,
+} from "../bw/card-input.ts";
+import { CliError, ExitCode } from "./errors.ts";
+import {
+	CARD_NUMBER_FAMILY,
+	CVV_FAMILY,
+	listUsedSourceFlags,
+	typeOnlyTextInputFlags,
+	type ItemTextInputs,
+	type ResolvedItemTextInputs,
+} from "./input.ts";
+
+/**
+ * The card values that are not secrets. The number and CVV are secrets, so they
+ * live in the shared text-input table with every other `--x-stdin|file|env`
+ * family; these are plain flags.
+ */
+export interface CardOptionInputs {
+	cardholder?: string;
+	brand?: string;
+	expiry?: string;
+	expMonth?: string;
+	expYear?: string;
+}
+
+/** `edit` only: clearing a value is different from leaving it alone. */
+export interface CardRemovalInputs {
+	rmNumber?: boolean;
+	rmCvv?: boolean;
+	rmCardholder?: boolean;
+	rmBrand?: boolean;
+	rmExpiry?: boolean;
+}
+
+type CardInputs = CardOptionInputs & CardRemovalInputs & ItemTextInputs;
+
+const CARD_OPTION_FLAGS: Array<[keyof CardOptionInputs, string]> = [
+	["cardholder", "--cardholder"],
+	["brand", "--brand"],
+	["expiry", "--expiry"],
+	["expMonth", "--exp-month"],
+	["expYear", "--exp-year"],
+];
+
+const CARD_REMOVAL_FLAGS: Array<[keyof CardRemovalInputs, string]> = [
+	["rmNumber", "--rm-number"],
+	["rmCvv", "--rm-cvv"],
+	["rmCardholder", "--rm-cardholder"],
+	["rmBrand", "--rm-brand"],
+	["rmExpiry", "--rm-expiry"],
+];
+
+export function registerCardOptions(command: Command): Command {
+	return command
+		.option("--cardholder <name>", "Cardholder name (card items only)")
+		.option("--brand <brand>", "Card brand, e.g. Visa, Mastercard, Amex (inferred from the number if omitted)")
+		.option("--expiry <MM/YY>", "Expiry as MM/YY or MM/YYYY")
+		.option("--exp-month <1-12>", "Expiry month")
+		.option("--exp-year <YYYY>", "Expiry year");
+}
+
+export function registerCardRemovalOptions(command: Command): Command {
+	return command
+		.option("--rm-number", "Remove the stored card number")
+		.option("--rm-cvv", "Remove the stored CVV")
+		.option("--rm-cardholder", "Remove the stored cardholder name")
+		.option("--rm-brand", "Remove the stored brand")
+		.option("--rm-expiry", "Remove the stored expiry month and year");
+}
+
+/**
+ * Every card-only flag the caller used — the set a command must reject on an
+ * item that has no card object to store them in.
+ */
+export function usedCardOnlyFlags(inputs: CardInputs): string[] {
+	const pairs: Array<[keyof CardInputs, string]> = [
+		...typeOnlyTextInputFlags("card"),
+		...CARD_OPTION_FLAGS,
+		...CARD_REMOVAL_FLAGS,
+	];
+	return pairs.filter(([key]) => Boolean(inputs[key])).map(([, flag]) => flag);
+}
+
+/**
+ * Turns the parsed flags into the card keys to write: a value sets a key, `null`
+ * clears it, and a key left out is left alone. `current` is the card being
+ * edited, so a brand is only inferred onto a card that has none.
+ */
+export function resolveCardPatch(
+	inputs: CardInputs,
+	secrets: ResolvedItemTextInputs,
+	current?: BwCard | null,
+): BwCard {
+	const card: BwCard = {};
+
+	if (secrets.number !== undefined) card.number = secrets.number;
+	if (inputs.rmNumber) card.number = null;
+
+	if (secrets.cvv !== undefined) card.code = secrets.cvv;
+	if (inputs.rmCvv) card.code = null;
+
+	if (inputs.cardholder !== undefined) card.cardholderName = inputs.cardholder;
+	if (inputs.rmCardholder) card.cardholderName = null;
+
+	if (inputs.brand !== undefined) {
+		card.brand = normalizeBrand(inputs.brand);
+	} else if (inputs.rmBrand) {
+		card.brand = null;
+	} else if (card.number && !current?.brand) {
+		const inferred = inferBrand(card.number);
+		if (inferred) card.brand = inferred;
+	}
+
+	if (inputs.expiry !== undefined) {
+		const expiry = parseExpiry(inputs.expiry);
+		card.expMonth = expiry.month;
+		card.expYear = expiry.year;
+	}
+	if (inputs.expMonth !== undefined) card.expMonth = parseExpMonth(inputs.expMonth);
+	if (inputs.expYear !== undefined) card.expYear = parseExpYear(inputs.expYear);
+	if (inputs.rmExpiry) {
+		card.expMonth = null;
+		card.expYear = null;
+	}
+
+	return card;
+}
+
+/**
+ * Setting and clearing the same value in one call has no sensible winner, and
+ * `--expiry` already names both halves `--exp-month` and `--exp-year` would set.
+ * Checked before any value is read, so a rejected call never consumes stdin.
+ */
+export function assertCardIntent(inputs: CardInputs): void {
+	const conflicts: Array<[boolean | undefined, string, string[]]> = [
+		[inputs.expiry !== undefined, "--expiry", usedOptionFlags(inputs, ["expMonth", "expYear"])],
+		[inputs.rmNumber, "--rm-number", listUsedSourceFlags(CARD_NUMBER_FAMILY, inputs)],
+		[inputs.rmCvv, "--rm-cvv", listUsedSourceFlags(CVV_FAMILY, inputs)],
+		[inputs.rmCardholder, "--rm-cardholder", usedOptionFlags(inputs, ["cardholder"])],
+		[inputs.rmBrand, "--rm-brand", usedOptionFlags(inputs, ["brand"])],
+		[inputs.rmExpiry, "--rm-expiry", usedOptionFlags(inputs, ["expiry", "expMonth", "expYear"])],
+	];
+
+	for (const [active, flag, setters] of conflicts) {
+		if (active && setters.length > 0) {
+			throw new CliError(
+				`${flag} cannot be combined with ${setters.join(", ")}.`,
+				ExitCode.BadArgs,
+			);
+		}
+	}
+}
+
+/** The flags among `keys` the caller passed, in help-text order. */
+function usedOptionFlags(
+	inputs: CardOptionInputs,
+	keys: Array<keyof CardOptionInputs>,
+): string[] {
+	return CARD_OPTION_FLAGS.filter(
+		([key]) => keys.includes(key) && inputs[key] !== undefined,
+	).map(([, flag]) => flag);
+}