bwx 0.5.0 → 0.6.1

package/src/bw/totp.ts

@@ -0,0 +1,246 @@
+import { createHmac } from "node:crypto";
+import { CliError, ExitCode } from "../cli/errors.ts";
+
+/**
+ * TOTP handling, kept local so a code costs no extra `bw` spawn and can be
+ * reported with the time it has left.
+ *
+ * Only shapes this module can compute *exactly* are computed here. Anything
+ * else — a `steam://` secret, an unknown algorithm, a seed that will not decode
+ * — is reported as unsupported so the caller can fall back to `bw get totp`.
+ * A wrong six-digit code is indistinguishable from a right one until the login
+ * fails, so guessing is never the safer option.
+ */
+
+/** RFC 4648 base32, minus the padding and separators authenticators sprinkle in. */
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+const STEAM_PREFIX = "steam://";
+
+export const DEFAULT_PERIOD = 30;
+export const DEFAULT_DIGITS = 6;
+export const DEFAULT_ALGORITHM = "SHA1";
+
+const SUPPORTED_ALGORITHMS: Record<string, string> = {
+	SHA1: "sha1",
+	SHA256: "sha256",
+	SHA512: "sha512",
+};
+
+export interface TotpConfig {
+	/** Normalized base32 secret, without padding or separators. */
+	secret: string;
+	period: number;
+	digits: number;
+	/** Uppercase name as it appears in an `otpauth://` URI. */
+	algorithm: string;
+}
+
+export interface TotpCode {
+	code: string;
+	period: number;
+	/** Whole seconds this code stays valid, counting the current one. */
+	secondsRemaining: number;
+}
+
+/** Why a stored secret cannot be computed locally, for the fallback path. */
+export class TotpUnsupportedError extends Error {}
+
+/**
+ * Reads a stored `login.totp` value. Bitwarden accepts a bare base32 secret, a
+ * full `otpauth://` URI, or a `steam://` secret, and all three turn up in real
+ * vaults.
+ */
+export function parseTotpSecret(raw: string): TotpConfig {
+	const value = raw.trim();
+
+	if (value.length === 0) {
+		throw new TotpUnsupportedError("secret is empty");
+	}
+
+	if (value.toLowerCase().startsWith(STEAM_PREFIX)) {
+		// Steam's alphabet and digit count differ from RFC 6238, and bwx has no
+		// way to verify its output against a real Steam login.
+		throw new TotpUnsupportedError("steam:// secrets are computed by bw");
+	}
+
+	const config = value.toLowerCase().startsWith("otpauth://")
+		? parseOtpauthUri(value)
+		: {
+				secret: normalizeBase32(value),
+				period: DEFAULT_PERIOD,
+				digits: DEFAULT_DIGITS,
+				algorithm: DEFAULT_ALGORITHM,
+			};
+
+	if (!(config.algorithm in SUPPORTED_ALGORITHMS)) {
+		throw new TotpUnsupportedError(`unsupported algorithm ${config.algorithm}`);
+	}
+
+	if (!isBase32(config.secret)) {
+		throw new TotpUnsupportedError("secret is not base32");
+	}
+
+	return config;
+}
+
+function parseOtpauthUri(value: string): TotpConfig {
+	let url: URL;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new TotpUnsupportedError("otpauth URI does not parse");
+	}
+
+	if (url.host.toLowerCase() !== "totp") {
+		throw new TotpUnsupportedError(`otpauth type "${url.host}" is not totp`);
+	}
+
+	const secret = url.searchParams.get("secret");
+	if (!secret) throw new TotpUnsupportedError("otpauth URI has no secret");
+
+	return {
+		secret: normalizeBase32(secret),
+		period: readPositiveInt(url, "period", DEFAULT_PERIOD),
+		digits: readPositiveInt(url, "digits", DEFAULT_DIGITS),
+		algorithm: (url.searchParams.get("algorithm") ?? DEFAULT_ALGORITHM).toUpperCase(),
+	};
+}
+
+function readPositiveInt(url: URL, name: string, fallback: number): number {
+	const raw = url.searchParams.get(name);
+	if (raw === null) return fallback;
+
+	const value = Number(raw);
+	if (!Number.isInteger(value) || value <= 0) {
+		throw new TotpUnsupportedError(`otpauth ${name}="${raw}" is not a positive integer`);
+	}
+	return value;
+}
+
+/** Uppercases and drops the spaces, hyphens, and padding authenticators show. */
+export function normalizeBase32(value: string): string {
+	return value.replace(/[\s-]/g, "").replace(/=+$/, "").toUpperCase();
+}
+
+function isBase32(value: string): boolean {
+	return value.length > 0 && /^[A-Z2-7]+$/.test(value);
+}
+
+/**
+ * Decodes base32 into bytes, discarding the trailing bits when the secret is not
+ * a whole number of bytes. Real secrets do this — a 29-character seed carries
+ * 145 bits and yields 18 bytes — and bw resolves them the same way, so rejecting
+ * them or padding them out would produce codes that quietly disagree with bw's.
+ */
+export function base32Decode(value: string): Buffer {
+	const bytes: number[] = [];
+	let accumulator = 0;
+	let bits = 0;
+
+	for (const char of value) {
+		const index = BASE32_ALPHABET.indexOf(char);
+		if (index === -1) {
+			throw new TotpUnsupportedError(`invalid base32 character "${char}"`);
+		}
+
+		accumulator = (accumulator << 5) | index;
+		bits += 5;
+
+		if (bits >= 8) {
+			bits -= 8;
+			bytes.push((accumulator >> bits) & 0xff);
+		}
+	}
+
+	if (bytes.length === 0) {
+		throw new TotpUnsupportedError("secret decodes to no bytes");
+	}
+
+	return Buffer.from(bytes);
+}
+
+/** Seconds left in the window `at` falls in, counting the current second. */
+export function secondsRemaining(period: number, at: number = Date.now()): number {
+	return period - (Math.floor(at / 1000) % period);
+}
+
+export function generateTotp(config: TotpConfig, at: number = Date.now()): TotpCode {
+	const key = base32Decode(config.secret);
+	const counter = Math.floor(at / 1000 / config.period);
+
+	const message = Buffer.alloc(8);
+	message.writeUInt32BE(Math.floor(counter / 2 ** 32), 0);
+	message.writeUInt32BE(counter >>> 0, 4);
+
+	const digest = createHmac(SUPPORTED_ALGORITHMS[config.algorithm]!, key)
+		.update(message)
+		.digest();
+
+	// RFC 6238 dynamic truncation: the low nibble of the last byte picks the
+	// four-byte window, and the high bit is masked off to stay sign-agnostic.
+	const offset = digest[digest.length - 1]! & 0x0f;
+	const binary = digest.readUInt32BE(offset) & 0x7fffffff;
+
+	return {
+		code: String(binary % 10 ** config.digits).padStart(config.digits, "0"),
+		period: config.period,
+		secondsRemaining: secondsRemaining(config.period, at),
+	};
+}
+
+/**
+ * Validates a secret on its way *into* the vault. A seed is only ever exercised
+ * at login, so a typo accepted here surfaces when the caller is already locked
+ * out — the one moment they cannot fix it. Returns the value to store.
+ */
+export function normalizeTotpInput(raw: string): string {
+	const value = raw.trim();
+
+	if (value.length === 0) {
+		throw new CliError("TOTP secret cannot be empty", ExitCode.BadArgs);
+	}
+
+	// Stored verbatim: bw owns these, and bwx would only mangle them.
+	if (value.toLowerCase().startsWith(STEAM_PREFIX)) return value;
+
+	if (value.toLowerCase().startsWith("otpauth://")) {
+		try {
+			parseTotpSecret(value);
+		} catch (err) {
+			throw new CliError(
+				`Invalid otpauth URI: ${describe(err)}`,
+				ExitCode.BadArgs,
+			);
+		}
+		return value;
+	}
+
+	const secret = normalizeBase32(value);
+	if (!isBase32(secret)) {
+		throw new CliError(
+			`Invalid TOTP secret: expected base32 (A-Z, 2-7) or an otpauth:// URI, got "${redact(value)}"`,
+			ExitCode.BadArgs,
+		);
+	}
+
+	// A secret shorter than a byte cannot key an HMAC.
+	try {
+		base32Decode(secret);
+	} catch (err) {
+		throw new CliError(`Invalid TOTP secret: ${describe(err)}`, ExitCode.BadArgs);
+	}
+
+	return secret;
+}
+
+/** Keeps a rejected secret out of logs while still showing what was wrong with it. */
+function redact(value: string): string {
+	const bad = value.replace(/[A-Za-z0-9\s=-]/g, "");
+	if (bad.length > 0) return `…contains "${[...new Set(bad)].join("")}"`;
+	return `…${value.length} characters`;
+}
+
+function describe(err: unknown): string {
+	return err instanceof Error ? err.message : String(err);
+}

package/src/cli/commands/create.ts

@@ -41,6 +41,10 @@ const LOGIN_ONLY_FLAGS: Array<[keyof CreateOptions, string]> = [
 	["passwordFile", "--password-file"],
 	["passwordEnv", "--password-env"],
 	["passwordGenerate", "--password-generate"],
+	["totp", "--totp"],
+	["totpStdin", "--totp-stdin"],
+	["totpFile", "--totp-file"],
+	["totpEnv", "--totp-env"],
 ];
 
 export function registerCreate(program: Command): void {
@@ -58,6 +62,10 @@ export function registerCreate(program: Command): void {
 		.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("--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, [])
@@ -139,6 +147,7 @@ export function registerCreate(program: Command): void {
 					notes: notes ?? null,
 					username: localOpts.username ?? null,
 					password: textInputs.password ?? null,
+					totp: textInputs.totp ?? null,
 					uris: localOpts.uri,
 					fields,
 					folderId: localOpts.folder

package/src/cli/commands/edit.ts

@@ -27,6 +27,7 @@ interface EditOptions extends ItemTextInputs {
 	addFieldFile: string[];
 	addFieldEnv: string[];
 	rmField: string[];
+	rmTotp?: boolean;
 	folder?: string;
 	favorite?: boolean;
 	fromJson?: boolean;
@@ -40,6 +41,11 @@ const LOGIN_ONLY_FLAGS: Array<[keyof EditOptions, string]> = [
 	["passwordFile", "--password-file"],
 	["passwordEnv", "--password-env"],
 	["passwordGenerate", "--password-generate"],
+	["totp", "--totp"],
+	["totpStdin", "--totp-stdin"],
+	["totpFile", "--totp-file"],
+	["totpEnv", "--totp-env"],
+	["rmTotp", "--rm-totp"],
 ];
 
 export function registerEdit(program: Command): void {
@@ -57,6 +63,11 @@ export function registerEdit(program: Command): void {
 		.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("--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, [])
 		.option("--add-field-file <kv>", "Add/update field value from file k=path", collect, [])
@@ -91,6 +102,7 @@ export function registerEdit(program: Command): void {
 					encoded = bwEncode(stdinText);
 				} else {
 					assertLoginFlags(localOpts, current);
+					assertTotpIntent(localOpts);
 
 					assertSingleStdinSource(
 						listExplicitStdinInputs({
@@ -119,6 +131,7 @@ export function registerEdit(program: Command): void {
 						notes: textInputs.notes,
 						username: localOpts.username,
 						password: textInputs.password,
+						totp: localOpts.rmTotp ? null : textInputs.totp,
 						uris: localOpts.uri.length > 0 ? localOpts.uri : undefined,
 						addFields,
 						rmFields: localOpts.rmField,
@@ -145,6 +158,28 @@ export function registerEdit(program: Command): void {
 		});
 }
 
+/**
+ * Setting and clearing the same secret in one call has no sensible winner, and
+ * picking one silently would either drop a seed or fail to remove one.
+ */
+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);
+
+	if (setters.length > 0) {
+		throw new CliError(
+			`--rm-totp cannot be combined with ${setters.join(", ")}.`,
+			ExitCode.BadArgs,
+		);
+	}
+}
+
 /**
  * Same trap as `create`: only a login item has somewhere to put a password, so
  * setting one on a note would be accepted and then quietly lost.

package/src/cli/commands/get.ts

@@ -1,8 +1,12 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
-import { emitData } from "../io.ts";
-import { readItemField } from "../../bw/fields.ts";
-import { CliError } from "../errors.ts";
+import { emitData, emitLog } from "../io.ts";
+import { readItemField, readTotp, readTotpSecret } from "../../bw/fields.ts";
+import { CliError, ExitCode } from "../errors.ts";
+import type { GlobalOptions } from "../types.ts";
+
+/** Seconds left below which `--fresh` waits, when the flag is given bare. */
+const DEFAULT_FRESH_SECONDS = 5;
 
 export function registerGet(program: Command): void {
 	program
@@ -10,8 +14,26 @@ export function registerGet(program: Command): void {
 		.description("Get a field from a vault item (built-in or custom)")
 		.argument("<field>", "Field: password | username | totp | notes | uri | item | <custom>")
 		.argument("<item>", "Item name or ID")
-		.action(async function (this: Command, field: string, item: string) {
+		.option(
+			"--fresh [seconds]",
+			`Wait for the next TOTP window if fewer than N seconds remain (default ${DEFAULT_FRESH_SECONDS})`,
+		)
+		.option("--seed", "Emit the stored TOTP secret instead of a code")
+		.action(async function (
+			this: Command,
+			field: string,
+			item: string,
+			localOpts: { fresh?: string | boolean; seed?: boolean },
+		) {
 			const opts = getGlobalOpts(this);
+
+			if (field === "totp") {
+				await emitTotp(item, localOpts, opts);
+				return;
+			}
+
+			assertTotpOnlyFlags(field, localOpts);
+
 			const value = await readItemField(field, item, opts);
 			// `item` is the one field that is itself JSON — emit it as structure.
 			emitData(field === "item" ? JSON.parse(value) : value, opts);
@@ -37,6 +59,83 @@ export function registerGet(program: Command): void {
 		});
 }
 
+/**
+ * Emits a TOTP alongside how long it stays valid. The remainder rides in the
+ * `--json` envelope's `meta` rather than replacing `data`, so `data` is still
+ * the plain code every other field returns and existing parsers keep working.
+ */
+async function emitTotp(
+	item: string,
+	localOpts: { fresh?: string | boolean; seed?: boolean },
+	opts: GlobalOptions,
+): Promise<void> {
+	if (localOpts.seed) {
+		if (localOpts.fresh !== undefined) {
+			throw new CliError(
+				"--seed and --fresh cannot be combined: a stored secret has no window.",
+				ExitCode.BadArgs,
+			);
+		}
+		emitData(await readTotpSecret(item, opts), opts);
+		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);
+	}
+
+	emitLog(`Valid for ${totp.secondsRemaining}s`, opts);
+	emitData(totp.code, opts, {
+		secondsRemaining: totp.secondsRemaining,
+		period: totp.period,
+	});
+}
+
+/**
+ * `--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;
+	if (raw === true) return DEFAULT_FRESH_SECONDS;
+
+	const value = Number(raw.trim());
+	if (!Number.isInteger(value) || value < 0) {
+		throw new CliError(
+			`Invalid --fresh "${raw}". Use a non-negative integer of seconds.`,
+			ExitCode.BadArgs,
+		);
+	}
+	return value;
+}
+
+/**
+ * Accepting `--fresh` on a password would read as "give me a fresh password",
+ * which is not what it does. Rejecting it beats quietly ignoring it.
+ */
+function assertTotpOnlyFlags(
+	field: string,
+	localOpts: { fresh?: string | boolean; seed?: boolean },
+): void {
+	const used = [
+		localOpts.fresh !== undefined ? "--fresh" : null,
+		localOpts.seed ? "--seed" : null,
+	].filter((flag): flag is string => flag !== null);
+
+	if (used.length > 0) {
+		throw new CliError(
+			`${used.join(", ")} ${used.length > 1 ? "apply" : "applies"} to 'get totp', not '${field}'.`,
+			ExitCode.BadArgs,
+		);
+	}
+}
+
 /**
  * `bwx field` took `<item> <name>` until 0.5.0. A caller using the old order
  * fails somewhere unhelpful — a missing item, or a missing field on the wrong

package/src/cli/input.ts

@@ -1,4 +1,5 @@
 import { parseFieldFlag, type ParsedField } from "../bw/encoding.ts";
+import { normalizeTotpInput } from "../bw/totp.ts";
 import { CliError, ExitCode } from "./errors.ts";
 
 export function collect(val: string, prev: string[]): string[] {
@@ -59,6 +60,10 @@ export interface ItemTextInputs {
 	passwordFile?: string;
 	passwordEnv?: string;
 	passwordGenerate?: boolean;
+	totp?: string;
+	totpStdin?: boolean;
+	totpFile?: string;
+	totpEnv?: string;
 }
 
 export interface ResolvedItemTextInputs {
@@ -66,6 +71,8 @@ export interface ResolvedItemTextInputs {
 	password?: string;
 	/** True when the password was generated, so callers can keep it unprinted. */
 	passwordGenerated?: boolean;
+	/** Normalized and validated by {@link normalizeTotpInput} before it is stored. */
+	totp?: string;
 }
 
 export interface ExplicitStdinInputs extends ItemTextInputs {
@@ -81,6 +88,7 @@ const PASSWORD_SOURCE_FLAGS = [
 	"--password-env",
 	"--password-generate",
 ];
+const TOTP_SOURCE_FLAGS = ["--totp", "--totp-stdin", "--totp-file", "--totp-env"];
 
 export async function resolveItemTextInputs(
 	inputs: ItemTextInputs,
@@ -89,7 +97,7 @@ export async function resolveItemTextInputs(
 ): Promise<ResolvedItemTextInputs> {
 	assertSingleStdinSource(listExplicitStdinInputs(inputs));
 
-	const [notes, password] = await Promise.all([
+	const [notes, password, totp] = await Promise.all([
 		resolveOptionalTextSource(
 			{
 				label: "notes",
@@ -115,12 +123,26 @@ export async function resolveItemTextInputs(
 			},
 			stdin,
 		),
+		resolveOptionalTextSource(
+			{
+				label: "TOTP secret",
+				inline: inputs.totp,
+				stdin: inputs.totpStdin,
+				file: inputs.totpFile,
+				env: inputs.totpEnv,
+				flagNames: TOTP_SOURCE_FLAGS,
+			},
+			stdin,
+		),
 	]);
 
 	return {
 		notes,
 		password,
 		passwordGenerated: inputs.passwordGenerate ?? false,
+		// Validated here rather than at the call sites so every write path gets
+		// the check: a malformed seed is only ever noticed at the login it breaks.
+		totp: totp === undefined ? undefined : normalizeTotpInput(totp),
 	};
 }
 
@@ -129,6 +151,8 @@ export function listExplicitStdinInputs(inputs: ExplicitStdinInputs): string[] {
 		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)
 			: []),

package/src/cli/items.ts

@@ -107,12 +107,14 @@ export function writeItems(
 }
 
 function plainLine(summary: ItemSummary): string {
-	return `${summary.id}\t${summary.type}\t${summary.name}\t${summary.username ?? "-"}`;
+	const totp = summary.hasTotp ? "totp" : "-";
+	return `${summary.id}\t${summary.type}\t${summary.name}\t${summary.username ?? "-"}\t${totp}`;
 }
 
 function humanLine(summary: ItemSummary): string {
 	const userPart = summary.username ? pc.dim(` (${summary.username})`) : "";
-	return `${pc.dim(summary.id)}  ${pc.cyan(summary.type)}  ${summary.name}${userPart}`;
+	const totpPart = summary.hasTotp ? " " + pc.yellow("2fa") : "";
+	return `${pc.dim(summary.id)}  ${pc.cyan(summary.type)}  ${summary.name}${userPart}${totpPart}`;
 }
 
 function writeLines<T>(values: T[], format: (value: T) => string): void {

package/src/config/paths.ts

@@ -8,5 +8,7 @@ export const CONFIG_DIR = `${CONFIG_HOME}/bwx`;
 export const CONFIG_FILE = `${CONFIG_DIR}/config.json`;
 /** Cached `bw` session token (owner-only). */
 export const SESSION_FILE = `${CONFIG_DIR}/session`;
+/** Cross-process gate used only while establishing a session. */
+export const SESSION_LOCK_DIR = `${CONFIG_DIR}/session.lock`;
 /** Cached vault-freshness snapshot — see bw/freshness.ts. */
 export const STATE_FILE = `${CONFIG_DIR}/state.json`;