bwx 0.4.1 → 0.6.0

package/src/bw/fields.ts

@@ -4,7 +4,15 @@ import type { GlobalOptions } from "../cli/types.ts";
 import { summarizeItem, type ItemSummary } from "./items.ts";
 import { runBwOrThrow } from "./runner.ts";
 import { withSession } from "./session.ts";
-import { BwItemSchema } from "./types.ts";
+import {
+	DEFAULT_PERIOD,
+	generateTotp,
+	parseTotpSecret,
+	secondsRemaining,
+	TotpUnsupportedError,
+	type TotpCode,
+} from "./totp.ts";
+import { BwItemSchema, type BwItem } from "./types.ts";
 
 /** Fields `bw get` resolves natively; anything else is a custom field name. */
 const BUILTIN_FIELDS = [
@@ -20,6 +28,11 @@ function isBuiltinField(field: string): boolean {
 	return (BUILTIN_FIELDS as readonly string[]).includes(field);
 }
 
+/** True when `field` should be read as the item's TOTP rather than a custom field. */
+function isTotpField(field: string, options?: ReadFieldOptions): boolean {
+	return field === "totp" && !options?.customOnly;
+}
+
 export interface ReadFieldOptions {
 	/**
 	 * Always resolve `field` as a custom field name, so an item whose custom
@@ -28,10 +41,23 @@ export interface ReadFieldOptions {
 	customOnly?: boolean;
 }
 
+/**
+ * Raised when the item was found but the requested field was not. Distinct from
+ * a missing *item* so the "did you mean this item?" suggestions below never fire
+ * on an error that already names the fields that do exist.
+ */
+class FieldMissingError extends CliError {}
+
+/** One `(field, item)` pair to resolve — see {@link readFields}. */
+export interface FieldRequest {
+	field: string;
+	item: string;
+	options?: ReadFieldOptions;
+}
+
 /**
  * Reads one field from a vault item and returns it verbatim (`item` yields the
  * item JSON), leaving the caller to decide whether the value is printed at all.
- * Ambiguous item lookups fail with the candidate list instead of a raw bw error.
  */
 export async function readItemField(
 	field: string,
@@ -39,22 +65,205 @@ export async function readItemField(
 	opts: GlobalOptions,
 	options?: ReadFieldOptions,
 ): Promise<string> {
-	try {
+	return withLookupHelp(item, opts, async () => {
+		if (isTotpField(field, options)) {
+			return (await resolveTotp(await fetchItem(item, opts), item, opts)).code;
+		}
+
 		return isBuiltinField(field) && !options?.customOnly
-			? await readBuiltinField(field, item, opts)
-			: await readCustomField(field, item, opts);
+			? readBuiltinField(field, item, opts)
+			: readCustomField(field, item, opts);
+	});
+}
+
+/**
+ * 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.
+ */
+export async function readTotp(
+	item: string,
+	opts: GlobalOptions,
+): Promise<TotpCode> {
+	return withLookupHelp(item, opts, async () =>
+		resolveTotp(await fetchItem(item, opts), item, opts),
+	);
+}
+
+/** The stored secret itself, for moving a seed back out to another authenticator. */
+export async function readTotpSecret(
+	item: string,
+	opts: GlobalOptions,
+): Promise<string> {
+	return withLookupHelp(item, opts, async () => {
+		const fetched = await fetchItem(item, opts);
+		return requireStoredTotp(fetched);
+	});
+}
+
+function requireStoredTotp(item: BwItem): string {
+	const stored = item.login?.totp;
+	if (!stored) {
+		throw new FieldMissingError(
+			`No totp found for item: ${item.name}`,
+			ExitCode.NotFound,
+		);
+	}
+	return stored;
+}
+
+/**
+ * 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.
+ */
+async function resolveTotp(
+	fetched: BwItem,
+	item: string,
+	opts: GlobalOptions,
+): Promise<TotpCode> {
+	const stored = requireStoredTotp(fetched);
+
+	try {
+		return generateTotp(parseTotpSecret(stored));
+	} catch (err) {
+		if (!(err instanceof TotpUnsupportedError)) throw err;
+
+		return {
+			code: await readBuiltinField("totp", item, opts),
+			period: DEFAULT_PERIOD,
+			secondsRemaining: secondsRemaining(DEFAULT_PERIOD),
+		};
+	}
+}
+
+/**
+ * Resolves many fields at once, paying a single `bw get item` per distinct item
+ * rather than one `bw` spawn per field. Each spawn costs ~2.5s, so a caller
+ * pulling a username and password from one item halves its own runtime. `totp`
+ * joins that batch too, since the code is computed from the secret the fetch
+ * already returned.
+ *
+ * Returns values positionally aligned with `requests`.
+ */
+export async function readFields(
+	requests: FieldRequest[],
+	opts: GlobalOptions,
+): Promise<string[]> {
+	const values = new Array<string>(requests.length);
+	const byItem = new Map<string, number[]>();
+
+	for (const [index, request] of requests.entries()) {
+		const bucket = byItem.get(request.item);
+		if (bucket) bucket.push(index);
+		else byItem.set(request.item, [index]);
+	}
+
+	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));
+
+		for (const index of indexes) {
+			const request = requests[index]!;
+
+			if (isTotpField(request.field, request.options)) {
+				const totp = await withLookupHelp(item, opts, () =>
+					resolveTotp(fetched, item, opts),
+				);
+				values[index] = totp.code;
+			} else {
+				values[index] = extractField(fetched, request.field, request.options);
+			}
+		}
+	}
+
+	return values;
+}
+
+/**
+ * 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.
+ */
+async function withLookupHelp<T>(
+	item: string,
+	opts: GlobalOptions,
+	fn: () => Promise<T>,
+): Promise<T> {
+	try {
+		return await fn();
 	} catch (err) {
+		if (err instanceof FieldMissingError) throw err;
+
 		if (err instanceof CliError && /more than one result/i.test(err.message)) {
-			const matches = await findMatches(item);
 			throw new CliError(
-				formatAmbiguousError(item, matches, opts),
+				formatAmbiguous(item, await findMatches(item), opts),
 				ExitCode.BadArgs,
 			);
 		}
+
+		if (err instanceof CliError && err.exitCode === ExitCode.NotFound) {
+			throw new CliError(
+				formatNotFound(item, await findSimilar(item), opts),
+				ExitCode.NotFound,
+			);
+		}
+
 		throw err;
 	}
 }
 
+async function fetchItem(item: string, opts: GlobalOptions): Promise<BwItem> {
+	const json = await withSession(opts, () => runBwOrThrow(["get", "item", item]));
+	return BwItemSchema.parse(JSON.parse(json));
+}
+
+/** Mirrors what `bw get <field>` would have returned for an already-fetched item. */
+function extractField(
+	item: BwItem,
+	field: string,
+	options?: ReadFieldOptions,
+): string {
+	if (!isBuiltinField(field) || options?.customOnly) {
+		return pickCustomField(item, field);
+	}
+
+	if (field === "item") return JSON.stringify(item);
+
+	// 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;
+	switch (field) {
+		case "notes":
+			value = item.notes;
+			break;
+		case "uri":
+			value = item.login?.uris?.[0]?.uri ?? null;
+			break;
+		case "username":
+			value = item.login?.username ?? null;
+			break;
+		case "password":
+			value = item.login?.password ?? null;
+			break;
+		default:
+			throw new FieldMissingError(
+				`Field "${field}" cannot be read from a fetched item`,
+				ExitCode.NotFound,
+			);
+	}
+
+	if (!value) {
+		throw new FieldMissingError(
+			`No ${field} found for item: ${item.name}`,
+			ExitCode.NotFound,
+		);
+	}
+
+	return value;
+}
+
 async function readBuiltinField(
 	field: string,
 	item: string,
@@ -65,7 +274,7 @@ async function readBuiltinField(
 	);
 
 	if (!result) {
-		throw new CliError(
+		throw new FieldMissingError(
 			`No ${field} found for item: ${item}`,
 			ExitCode.NotFound,
 		);
@@ -79,20 +288,21 @@ async function readCustomField(
 	item: string,
 	opts: GlobalOptions,
 ): Promise<string> {
-	const json = await withSession(opts, () =>
-		runBwOrThrow(["get", "item", item]),
-	);
+	return pickCustomField(await fetchItem(item, opts), fieldName);
+}
 
-	const parsed = BwItemSchema.parse(JSON.parse(json));
-	const fields = parsed.fields ?? [];
+function pickCustomField(item: BwItem, fieldName: 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 msg = available
-			? `Field "${fieldName}" not found. Available: ${available}`
-			: `Field "${fieldName}" not found (item has no custom fields)`;
-		throw new CliError(msg, ExitCode.NotFound);
+		throw new FieldMissingError(
+			available
+				? `Field "${fieldName}" not found. Available: ${available}`
+				: `Field "${fieldName}" not found (item has no custom fields)`,
+			ExitCode.NotFound,
+		);
 	}
 
 	return match.value ?? "";
@@ -108,7 +318,95 @@ async function findMatches(query: string): Promise<ItemSummary[]> {
 	}
 }
 
-function formatAmbiguousError(
+/**
+ * Looks for what the caller probably meant. bw's own search already came back
+ * empty, so this pulls the item list once and scores it locally: one `bw` spawn
+ * on the error path, and matching that survives typos and extra words the way
+ * repeated `--search` calls do not.
+ */
+async function findSimilar(query: string): Promise<ItemSummary[]> {
+	let summaries: ItemSummary[];
+	try {
+		const json = await runBwOrThrow(["list", "items"]);
+		const items: Array<Record<string, unknown>> = JSON.parse(json);
+		summaries = items.map(summarizeItem);
+	} catch {
+		return [];
+	}
+
+	return rankSimilar(query, summaries);
+}
+
+/** Pure so the suggestion quality is testable without a vault. */
+export function rankSimilar(
+	query: string,
+	items: ItemSummary[],
+	max = MAX_SUGGESTIONS,
+): ItemSummary[] {
+	const tokens = tokenize(query);
+	if (tokens.length === 0) return [];
+
+	const scored = items
+		.map((item) => ({ item, score: scoreMatch(tokens, item) }))
+		.filter((entry) => entry.score > 0)
+		.sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name));
+
+	return scored.slice(0, max).map((entry) => entry.item);
+}
+
+/**
+ * Length gates on the fuzzier rules keep short words from matching by accident —
+ * without them "not" pulls in every item containing "evernote", and a suggestion
+ * list full of noise is worse than none.
+ */
+function scoreMatch(tokens: string[], item: ItemSummary): number {
+	const haystack = `${item.name} ${item.username ?? ""}`.toLowerCase();
+	const itemTokens = tokenize(haystack);
+
+	let score = 0;
+	for (const token of tokens) {
+		if (itemTokens.includes(token)) score += 3;
+		else if (token.length >= 4 && haystack.includes(token)) score += 2;
+		else if (
+			token.length >= 3 &&
+			itemTokens.some((other) => other.startsWith(token))
+		) {
+			score += 1;
+		}
+	}
+
+	return score;
+}
+
+function tokenize(value: string): string[] {
+	return value
+		.toLowerCase()
+		.split(/[^a-z0-9]+/)
+		.filter((token) => token.length >= 2);
+}
+
+const MAX_SUGGESTIONS = 5;
+
+function formatNotFound(
+	query: string,
+	matches: ItemSummary[],
+	opts: GlobalOptions,
+): string {
+	if (matches.length === 0) {
+		return `No item matching "${query}". Run 'bwx search <query>' to find it.`;
+	}
+
+	if (opts.json) {
+		return `No item matching "${query}". Did you mean: ${JSON.stringify(matches)}`;
+	}
+
+	return [
+		`No item matching "${query}". Did you mean:\n`,
+		...matches.map(formatCandidate),
+	].join("\n");
+}
+
+function formatAmbiguous(
 	query: string,
 	matches: ItemSummary[],
 	opts: GlobalOptions,
@@ -121,13 +419,14 @@ function formatAmbiguousError(
 		return `Multiple items match "${query}": ${JSON.stringify(matches)}`;
 	}
 
-	const lines = [`Multiple items match "${query}":\n`];
-	for (const m of matches) {
-		const user = m.username ? ` (${m.username})` : "";
-		lines.push(
-			`  ${pc.dim(m.id)}  ${pc.cyan(m.type)}  ${m.name}${pc.dim(user)}`,
-		);
-	}
-	lines.push(`\nUse a specific ID: ${pc.dim("bwx get <field> <id>")}`);
-	return lines.join("\n");
+	return [
+		`Multiple items match "${query}":\n`,
+		...matches.map(formatCandidate),
+		`\nUse a specific ID: ${pc.dim("bwx get <field> <id>")}`,
+	].join("\n");
+}
+
+function formatCandidate(match: ItemSummary): string {
+	const user = match.username ? ` (${match.username})` : "";
+	return `  ${pc.dim(match.id)}  ${pc.cyan(match.type)}  ${match.name}${pc.dim(user)}`;
 }

package/src/bw/folders.ts

@@ -0,0 +1,96 @@
+import pc from "picocolors";
+import { CliError, ExitCode } from "../cli/errors.ts";
+import type { GlobalOptions } from "../cli/types.ts";
+import { runBwOrThrow } from "./runner.ts";
+import { withSession } from "./session.ts";
+
+export interface BwFolder {
+	/** `null` is bw's "No Folder" bucket, which every unfiled item belongs to. */
+	id: string | null;
+	name: string;
+}
+
+const UUID_RE =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The spelling bw expects on `--folderid` for items that are in no folder. */
+export const NO_FOLDER = "null";
+
+export async function listFolders(opts: GlobalOptions): Promise<BwFolder[]> {
+	const json = await withSession(opts, () => runBwOrThrow(["list", "folders"]));
+	const raw = JSON.parse(json) as Array<Record<string, unknown>>;
+	return raw.map((folder) => ({
+		id: typeof folder.id === "string" ? folder.id : null,
+		name: String(folder.name ?? ""),
+	}));
+}
+
+/**
+ * Turns whatever the caller wrote in `--folder` into an id. IDs pass straight
+ * through, so this costs nothing for callers that already have one; names are
+ * resolved against the vault because a folder id is not something a human — or
+ * an agent reading `bwx list` output — can otherwise discover.
+ *
+ * Returns `null` for the "no folder" bucket (`--folder none`).
+ */
+export async function resolveFolderRef(
+	ref: string,
+	opts: GlobalOptions,
+): Promise<string | null> {
+	if (UUID_RE.test(ref)) return ref;
+	if (ref === NO_FOLDER || ref.toLowerCase() === "none") return null;
+
+	const folders = await listFolders(opts);
+	const named = folders.filter((folder) => folder.id !== null);
+
+	const exact = named.filter(
+		(folder) => folder.name.toLowerCase() === ref.toLowerCase(),
+	);
+	const matches =
+		exact.length > 0
+			? exact
+			: named.filter((folder) =>
+					folder.name.toLowerCase().includes(ref.toLowerCase()),
+				);
+
+	if (matches.length === 0) {
+		throw new CliError(
+			`No folder matching "${ref}". Run 'bwx folders' to list them.`,
+			ExitCode.NotFound,
+		);
+	}
+
+	if (matches.length > 1) {
+		throw new CliError(
+			formatAmbiguousFolders(ref, matches, opts),
+			ExitCode.BadArgs,
+		);
+	}
+
+	return matches[0]!.id;
+}
+
+/** Resolves `--folder` for read commands, where "no folder" is a real filter. */
+export async function resolveFolderFilter(
+	ref: string,
+	opts: GlobalOptions,
+): Promise<string> {
+	return (await resolveFolderRef(ref, opts)) ?? NO_FOLDER;
+}
+
+function formatAmbiguousFolders(
+	ref: string,
+	matches: BwFolder[],
+	opts: GlobalOptions,
+): string {
+	if (opts.json) {
+		return `Multiple folders match "${ref}": ${JSON.stringify(matches)}`;
+	}
+
+	const lines = [`Multiple folders match "${ref}":\n`];
+	for (const folder of matches) {
+		lines.push(`  ${pc.dim(folder.id ?? "-")}  ${folder.name}`);
+	}
+	lines.push(`\nUse the full name or its ID.`);
+	return lines.join("\n");
+}

package/src/bw/generate.ts

@@ -0,0 +1,91 @@
+import { CliError, ExitCode } from "../cli/errors.ts";
+import { runBwOrThrow } from "./runner.ts";
+
+/**
+ * `bw generate` is local — it needs no session and no unlocked vault, so a
+ * generated secret costs one fast spawn and never touches the network.
+ */
+
+export interface GenerateOptions {
+	length?: number;
+	passphrase?: boolean;
+	words?: number;
+	separator?: string;
+	capitalize?: boolean;
+	includeNumber?: boolean;
+	uppercase?: boolean;
+	lowercase?: boolean;
+	numbers?: boolean;
+	special?: boolean;
+	ambiguous?: boolean;
+}
+
+/** bw's own defaults, restated here so `--no-numbers` can turn one off without
+ * silently disabling the rest: bw needs every wanted character set named. */
+const CHARSET_DEFAULTS = {
+	uppercase: true,
+	lowercase: true,
+	numbers: true,
+	special: false,
+} as const;
+
+export function buildGenerateArgs(options: GenerateOptions): string[] {
+	const args = ["generate"];
+
+	if (options.passphrase) {
+		args.push("--passphrase");
+		if (options.words !== undefined) args.push("--words", String(options.words));
+		if (options.separator !== undefined) {
+			args.push("--separator", options.separator);
+		}
+		if (options.capitalize) args.push("--capitalize");
+		if (options.includeNumber) args.push("--includeNumber");
+		return args;
+	}
+
+	const charsets = {
+		uppercase: options.uppercase ?? CHARSET_DEFAULTS.uppercase,
+		lowercase: options.lowercase ?? CHARSET_DEFAULTS.lowercase,
+		numbers: options.numbers ?? CHARSET_DEFAULTS.numbers,
+		special: options.special ?? CHARSET_DEFAULTS.special,
+	};
+
+	if (!Object.values(charsets).some(Boolean)) {
+		throw new CliError(
+			"At least one character set must stay enabled.",
+			ExitCode.BadArgs,
+		);
+	}
+
+	if (options.length !== undefined) {
+		if (!Number.isInteger(options.length) || options.length < 5) {
+			throw new CliError(
+				`Invalid --length "${options.length}". Use an integer of at least 5.`,
+				ExitCode.BadArgs,
+			);
+		}
+		args.push("--length", String(options.length));
+	}
+
+	if (charsets.uppercase) args.push("--uppercase");
+	if (charsets.lowercase) args.push("--lowercase");
+	if (charsets.numbers) args.push("--number");
+	if (charsets.special) args.push("--special");
+	if (options.ambiguous) args.push("--ambiguous");
+
+	return args;
+}
+
+export async function generateSecret(
+	options: GenerateOptions,
+): Promise<string> {
+	const value = await runBwOrThrow(buildGenerateArgs(options), {
+		session: null,
+	});
+
+	if (!value) {
+		throw new CliError("bw generate returned nothing", ExitCode.BwError);
+	}
+
+	return value;
+}

package/src/bw/items.ts

@@ -10,16 +10,24 @@ export interface ItemSummary {
 	type: string;
 	name: string;
 	username: string | null;
+	/**
+	 * Whether the item carries a TOTP secret — the fact, never the secret.
+	 * Without it, finding which items have 2FA means `--full-items`, which dumps
+	 * every password and note in the vault to answer a boolean.
+	 */
+	hasTotp: boolean;
 }
 
 export function summarizeItem(item: Record<string, unknown>): ItemSummary {
 	const login = item.login as Record<string, unknown> | null | undefined;
 	const username = login?.username;
+	const totp = login?.totp;
 
 	return {
 		id: String(item.id ?? ""),
 		type: BW_TYPE_LABELS[item.type as number] ?? `type:${item.type}`,
 		name: String(item.name ?? ""),
 		username: typeof username === "string" && username ? username : null,
+		hasTotp: typeof totp === "string" && totp.length > 0,
 	};
 }

package/src/bw/session.ts

@@ -60,21 +60,47 @@ async function getMasterPassword(): Promise<string> {
 	return pw;
 }
 
+/**
+ * Whether reads will work right now without an unlock. `bw status` answers for
+ * the vault, not for us: it reports "locked" whenever the vault has no session
+ * of its own, even when bwx holds a cached one that works perfectly. Reporting
+ * that raw answer sends callers off to unlock a vault they can already read.
+ */
+export type SessionState =
+	/** Cached session works — reads succeed with no unlock. */
+	| "valid"
+	/** A session was cached but the vault no longer accepts it. */
+	| "stale"
+	/** Nothing cached; the next read unlocks. */
+	| "none";
+
+/** Confirms a token by asking the vault, which is the only authority on it. */
+async function sessionWorks(token: string): Promise<boolean> {
+	const check = await runBw(["status"], { session: token });
+	if (check.exitCode !== 0) return false;
+	try {
+		return (
+			BwStatusSchema.parse(JSON.parse(check.stdout)).status === "unlocked"
+		);
+	} catch {
+		return false;
+	}
+}
+
+export async function probeSessionState(
+	opts: GlobalOptions,
+): Promise<SessionState> {
+	const cached = getSession() || loadCachedSession(opts);
+	if (!cached) return "none";
+	return (await sessionWorks(cached)) ? "valid" : "stale";
+}
+
 export async function ensureUnlocked(opts: GlobalOptions): Promise<void> {
 	// Try cached session first
 	const cached = getSession() || loadCachedSession(opts);
 	if (cached) {
 		setSession(cached);
-		// Quick check — try a lightweight command
-		const check = await runBw(["status"]);
-		if (check.exitCode === 0) {
-			try {
-				const status = BwStatusSchema.parse(JSON.parse(check.stdout));
-				if (status.status === "unlocked") return;
-			} catch {
-				// Fall through
-			}
-		}
+		if (await sessionWorks(cached)) return;
 	}
 
 	const status = await getStatus();