bwx 0.5.0 → 0.6.0

package/README.md

@@ -70,6 +70,7 @@ unlock. `valid` means reads work now, `stale` means the cached session was rejec
 | Command | Description |
 |---------|-------------|
 | `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`) |
+| `bwx get totp <item>` | TOTP code (`--fresh [n]`, `--seed`) |
 | `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`) |
@@ -79,10 +80,17 @@ unlock. `valid` means reads work now, `stale` means the cached session was rejec
 | `bwx attach list <item>` | List attachments for an item |
 | `bwx attach get <item> <attachment>` | Download attachment by ID or filename |
 
-`search` and `list` print the same reduced projection — id, type, name, username — in
-human, `--plain`, and `--json` form, so asking for machine-readable output never widens
-what is exposed. `--full-items` is the explicit opt-in to complete item objects, which
-carry passwords, notes, and custom fields.
+`search` and `list` print the same reduced projection — id, type, name, username,
+hasTotp — in human, `--plain`, and `--json` form, so asking for machine-readable output
+never widens what is exposed. `--full-items` is the explicit opt-in to complete item
+objects, which carry passwords, notes, and custom fields.
+
+`hasTotp` reports that an item has a TOTP secret without carrying it, so finding your 2FA
+items does not mean dumping the vault:
+
+```bash
+bwx list --json --limit 0 | jq -r '.data[] | select(.hasTotp) | .name'
+```
 
 A lookup that finds nothing suggests what you probably meant, and one that matches
 several items lists them, so neither ends in a guessing round:
@@ -95,6 +103,42 @@ error: No item matching "GitHub PAT vforsh old". Did you mean:
   3683fb9a-…  note  GitHub PAT (yaforsh) [codex-monitor-pr]
 ```
 
+### TOTP
+
+Codes are computed locally from the stored secret. A TOTP therefore costs no extra `bw`
+spawn and batches with the other fields of the same item, and bwx can report how long the
+code has left.
+
+```bash
+bwx get totp "AWS"              # code on stdout, "Valid for 17s" on stderr
+bwx get totp "AWS" --json       # { "data": "123456", "meta": { "secondsRemaining": 17, "period": 30 } }
+bwx get totp "AWS" --fresh      # wait for the next window if under 5s remain
+bwx get totp "AWS" --fresh 15   # ...or under 15s
+bwx get totp "AWS" --seed       # the stored secret, for moving it to another authenticator
+```
+
+The remainder matters more than it looks: a vault read plus the time to actually use the
+code often leaves single-digit seconds, and a code that expires in transit fails the login
+without saying why. `--fresh` sleeps at most one period and hands back a full window.
+
+Bare base32 and `otpauth://` URIs are both understood, including non-default `period`,
+`digits`, and `algorithm` (SHA1/SHA256/SHA512). Secrets bwx will not compute exactly —
+`steam://`, unknown algorithms, anything that fails to decode — fall back to `bw get totp`
+rather than being guessed at, since a wrong code is indistinguishable from a right one
+until the login fails.
+
+Storing a secret:
+
+```bash
+BWX_SEED="JBSWY3DPEHPK3PXP" bwx create --type login --name "AWS" --username me --totp-env BWX_SEED
+bwx edit "AWS" --totp "otpauth://totp/AWS:me?secret=JBSWY3DPEHPK3PXP&issuer=AWS"
+bwx edit "AWS" --rm-totp
+```
+
+Spaces, hyphens, and `=` padding are stripped and case is normalized; an `otpauth://` URI
+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.
+
 ### Listings are capped
 
 Listings stop at 50 items by default — an uncapped `bwx list` returns the whole vault,
@@ -153,15 +197,15 @@ The check is cached in `~/.config/bwx/state.json`, so a fresh vault costs no ext
 
 | Command | Description |
 |---------|-------------|
-| `bwx create` | Create item (`--type`, `--name`, `--username`, `--password-stdin`, `--field-file k=path`) |
-| `bwx edit <item>` | Edit item (`--name`, `--password-env`, `--add-field-file k=path`, `--rm-field name`) |
+| `bwx create` | Create item (`--type`, `--name`, `--username`, `--password-stdin`, `--totp-env`, `--field-file k=path`) |
+| `bwx edit <item>` | Edit item (`--name`, `--password-env`, `--totp`, `--rm-totp`, `--add-field-file k=path`, `--rm-field name`) |
 | `bwx delete <item>` | Delete item (`--permanent`, `--force`) |
 | `bwx restore <item>` | Restore an item from the trash |
 | `bwx generate` | Generate a password or passphrase (local, no vault access) |
 
-Login-only flags (`--username`, any `--password-*`, `--uri`) require a login item. A
-secure note has nowhere to put them, so passing them to one is an error rather than an
-exit 0 over a credential that was silently dropped.
+Login-only flags (`--username`, any `--password-*` or `--totp-*`, `--uri`) require a login
+item. A secure note has nowhere to put them, so passing them to one is an error rather
+than an exit 0 over a credential that was silently dropped.
 
 `bwx delete` requires `--force` whenever it is not talking to a terminal. The confirmation
 prompt cannot render for a script or an agent, so without it `--force` would be decorative
@@ -217,6 +261,7 @@ bwx create --name "Acme" --field-file '!API Key=./token.txt' --field-env account
 Supported source flags:
 
 - Passwords: `--password-stdin`, `--password-file <path>`, `--password-env <name>`
+- TOTP secrets: `--totp-stdin`, `--totp-file <path>`, `--totp-env <name>`
 - Notes: `--notes-file <path>`
 - Create fields: `--field-file k=path`, `--field-env k=ENV`
 - Edit fields: `--add-field-file k=path`, `--add-field-env k=ENV`

package/package.json

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

package/skill/bwx/SKILL.md

@@ -11,7 +11,8 @@ Extended Bitwarden CLI. Wraps `bw` with auto-unlock, session caching, and struct
 
 ```bash
 bwx get password "GitHub"               # retrieve a password (auto-unlocks)
-bwx get totp "AWS (user@example.com)"   # TOTP code
+bwx get totp "AWS (user@example.com)"   # TOTP code (+ seconds left, on stderr)
+bwx get totp "AWS" --fresh              # wait out a nearly-expired code first
 bwx get username "GitHub"               # username
 bwx get notes "Deploy key"              # secure note content
 bwx get uri "GitHub"                    # first URI
@@ -49,6 +50,27 @@ 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
 suggestions instead of retrying variations — the answer is usually in them.
 
+### `bwx get totp <item>`
+
+Codes are computed locally from the stored secret, so a TOTP costs no extra `bw` spawn and
+batches with other fields from the same item.
+
+```bash
+bwx get totp "AWS"                  # code on stdout, "Valid for 17s" on stderr
+bwx get totp "AWS" --json           # { "data": "123456", "meta": { "secondsRemaining", "period" } }
+bwx get totp "AWS" --fresh          # wait for the next window if under 5s remain
+bwx get totp "AWS" --fresh 15       # ...or under 15s
+bwx get totp "AWS" --seed           # the stored secret, for migrating to another app
+```
+
+**Check `secondsRemaining` before using a code.** A `bw` read plus the time to hand the code
+over routinely leaves under 5 seconds, and a code that expires in transit fails the login
+with no useful error. `--fresh` sleeps at most one period and returns a full-window code.
+
+Accepts bare base32 and `otpauth://` URIs, honoring their `period`, `digits`, and
+`algorithm` (SHA1/SHA256/SHA512). `steam://` secrets and anything else bwx cannot compute
+exactly are delegated to `bw get totp` instead of guessed at.
+
 ### `bwx field <name> <item>`
 
 Custom fields only, so an item whose custom field is named `password` is still reachable.
@@ -59,8 +81,13 @@ Takes its arguments in the same order as `get` (this changed in 0.5.0).
 Flags: `--type login|note|card|identity`, `--folder <name|id>`, `--limit <n>`, `--full-items`
 
 Human, `--plain`, and `--json` output all carry the same reduced projection — `id`, `type`,
-`name`, `username` — so listings never leak passwords, notes, or custom fields. `--full-items`
-opts into complete item objects and **does** include secrets; avoid it in logged sessions.
+`name`, `username`, `hasTotp` — so listings never leak passwords, notes, or custom fields.
+`--full-items` opts into complete item objects and **does** include secrets; avoid it in
+logged sessions.
+
+`hasTotp` says whether an item has a TOTP secret, never what it is. Use it to find 2FA items
+(`bwx list --json --limit 0 | jq '.data[]|select(.hasTotp)'`) instead of reaching for
+`--full-items`, which would dump the whole vault in plaintext to answer a boolean.
 
 **Listings stop at 50 items** unless you pass `--limit` (`--limit 0` for all). Truncation is
 reported on stderr and in `meta` on the JSON envelope — check it before concluding a listing
@@ -99,10 +126,10 @@ Downloads an attachment by ID or filename. Defaults to saving as the attachment
 
 ### `bwx create [options]`
 
-Flags: `--type login|note`, `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--password-generate`, `--generate-length <n>`, `--uri` (repeatable), `--field k=v` (repeatable), `--field-file k=path`, `--field-env k=ENV`, `--folder <name|id>`, `--favorite`, `--from-json`
+Flags: `--type login|note`, `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--password-generate`, `--generate-length <n>`, `--totp`, `--totp-stdin`, `--totp-file`, `--totp-env`, `--uri` (repeatable), `--field k=v` (repeatable), `--field-file k=path`, `--field-env k=ENV`, `--folder <name|id>`, `--favorite`, `--from-json`
 
-`--username`, any `--password-*`, and `--uri` require `--type login`; a note cannot hold
-them and passing them to one is now an error rather than a silent drop.
+`--username`, any `--password-*` or `--totp-*`, and `--uri` require `--type login`; a note
+cannot hold them and passing them to one is now an error rather than a silent drop.
 
 Field syntax: `k=v` (text), `!k=v` (hidden), `bool:k=v` (boolean). The same key syntax works for `--field-file` and `--field-env`, where the value is a path or environment variable name. Stdin is read as `--notes` when piped; prefer `--password-stdin` for login passwords.
 
@@ -114,7 +141,24 @@ bwx edit "API Key" --add-field region=us-east-1
 printf '%s' "$TOKEN" | bwx edit "GitHub" --password-stdin --uri https://github.com
 bwx edit "Note" --rm-field old-key
 ```
-Flags: `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--password-generate`, `--generate-length <n>`, `--uri` (replaces all), `--add-field k=v`, `--add-field-file k=path`, `--add-field-env k=ENV`, `--rm-field name`, `--folder <name|id>` (`none` unfiles), `--favorite/--no-favorite`, `--from-json`
+Flags: `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--password-generate`, `--generate-length <n>`, `--totp`, `--totp-stdin`, `--totp-file`, `--totp-env`, `--rm-totp`, `--uri` (replaces all), `--add-field k=v`, `--add-field-file k=path`, `--add-field-env k=ENV`, `--rm-field name`, `--folder <name|id>` (`none` unfiles), `--favorite/--no-favorite`, `--from-json`
+
+### Storing a TOTP secret
+
+```bash
+BWX_SEED="JBSWY3DPEHPK3PXP" bwx create --type login --name "AWS" --username me --totp-env BWX_SEED
+bwx edit "AWS" --totp "otpauth://totp/AWS:me?secret=JBSWY3DPEHPK3PXP&issuer=AWS"
+bwx edit "AWS" --rm-totp
+```
+
+Takes a bare base32 secret (spaces, hyphens, and `=` padding are stripped; case is
+normalized) or a full `otpauth://` URI, which is stored verbatim so its `period`/`digits`/
+`algorithm` survive. Malformed secrets are rejected **before** the write — a bad seed
+otherwise sits in the vault until it fails the login it was meant to unlock, which is the
+one moment it cannot be fixed.
+
+Prefer `--totp-env` or `--totp-stdin` over `--totp`: a seed on the command line lands in
+shell history and `ps` output.
 
 ### `bwx delete <item>`
 
@@ -186,7 +230,9 @@ even under `--json`; `-q` silences them.
 - Prefer `--password-generate` over generating a secret yourself and passing it in.
 - Request the narrowest field, resolving an exact item ID first.
 - Use `-q` for command substitution so unlock logs cannot contaminate merged output.
-- On writes, prefer `--password-stdin`, `--password-env`, `--field-file`, `--field-env`.
+- On writes, prefer `--password-stdin`, `--password-env`, `--totp-stdin`, `--totp-env`, `--field-file`, `--field-env`.
+- Check `secondsRemaining` on a TOTP, or pass `--fresh`, before handing the code anywhere.
+- Use `hasTotp` on a listing to find 2FA items; never `--full-items` for that.
 - Never echo, log, checksum, or commit retrieved values; `unset` temporary variables.
 
 ## Auth

package/src/bw/encoding.ts

@@ -40,6 +40,7 @@ export interface NewItemOptions {
 	notes?: string | null;
 	username?: string | null;
 	password?: string | null;
+	totp?: string | null;
 	uris?: string[];
 	fields?: ParsedField[];
 	folderId?: string | null;
@@ -65,7 +66,7 @@ export function buildNewItem(options: NewItemOptions): Record<string, unknown> {
 		item.login = {
 			username: options.username ?? null,
 			password: options.password ?? null,
-			totp: null,
+			totp: options.totp ?? null,
 			uris: options.uris?.length
 				? options.uris.map((uri) => ({ match: null, uri }))
 				: null,
@@ -95,6 +96,8 @@ export interface PatchOptions {
 	notes?: string;
 	username?: string;
 	password?: string;
+	/** `null` clears the stored secret; `undefined` leaves it alone. */
+	totp?: string | null;
 	uris?: string[];
 	addFields?: ParsedField[];
 	rmFields?: string[];
@@ -115,10 +118,18 @@ export function patchItem(
 	if (patch.favorite !== undefined) result.favorite = patch.favorite;
 
 	// Login fields
-	if (patch.username !== undefined || patch.password !== undefined || patch.uris !== undefined) {
-		const login = (result.login as Record<string, unknown>) ?? {};
+	if (
+		patch.username !== undefined ||
+		patch.password !== undefined ||
+		patch.totp !== undefined ||
+		patch.uris !== undefined
+	) {
+		// Copied, not aliased: `{ ...item }` above is shallow, so assigning into
+		// the original `login` would edit the caller's item as a side effect.
+		const login = { ...((result.login as Record<string, unknown>) ?? {}) };
 		if (patch.username !== undefined) login.username = patch.username;
 		if (patch.password !== undefined) login.password = patch.password;
+		if (patch.totp !== undefined) login.totp = patch.totp;
 		if (patch.uris !== undefined) {
 			login.uris = patch.uris.map((uri) => ({ match: null, uri }));
 		}

package/src/bw/fields.ts

@@ -4,6 +4,14 @@ 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 {
+	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. */
@@ -16,16 +24,15 @@ const BUILTIN_FIELDS = [
 	"item",
 ] as const;
 
-/**
- * `totp` is a computed code, not stored data — only `bw get totp` can derive it,
- * so it is the one field that cannot be served from a fetched item.
- */
-const DERIVED_FIELDS = new Set(["totp"]);
-
 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
@@ -58,17 +65,85 @@ export async function readItemField(
 	opts: GlobalOptions,
 	options?: ReadFieldOptions,
 ): Promise<string> {
-	return withLookupHelp(item, opts, () =>
-		isBuiltinField(field) && !options?.customOnly
+	return withLookupHelp(item, opts, async () => {
+		if (isTotpField(field, options)) {
+			return (await resolveTotp(await fetchItem(item, opts), item, opts)).code;
+		}
+
+		return isBuiltinField(field) && !options?.customOnly
 			? readBuiltinField(field, item, opts)
-			: readCustomField(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.
+ * 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`.
  */
@@ -88,34 +163,25 @@ 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 derived = indexes.filter((i) => isDerived(requests[i]!));
-		const stored = indexes.filter((i) => !isDerived(requests[i]!));
+		const fetched = await withLookupHelp(item, opts, () => fetchItem(item, opts));
 
-		if (stored.length > 0) {
-			const fetched = await withLookupHelp(item, opts, () =>
-				fetchItem(item, opts),
-			);
-			for (const index of stored) {
-				const request = requests[index]!;
+		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);
 			}
 		}
-
-		for (const index of derived) {
-			const request = requests[index]!;
-			values[index] = await withLookupHelp(item, opts, () =>
-				readBuiltinField(request.field, item, opts),
-			);
-		}
 	}
 
 	return values;
 }
 
-function isDerived(request: FieldRequest): boolean {
-	return !request.options?.customOnly && DERIVED_FIELDS.has(request.field);
-}
-
 /**
  * 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.
@@ -165,14 +231,28 @@ function extractField(
 
 	if (field === "item") return JSON.stringify(item);
 
-	const value =
-		field === "notes"
-			? item.notes
-			: field === "uri"
-				? (item.login?.uris?.[0]?.uri ?? null)
-				: field === "username"
-					? (item.login?.username ?? null)
-					: (item.login?.password ?? null);
+	// 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(

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/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 {