bwx 0.5.0 → 0.6.1

package/README.md

@@ -17,7 +17,7 @@ Bitwarden CLI wrapper for AI agents (`bwx` = `bw extended`). Auto-unlock, sessio
 The native `bw` CLI requires interactive prompts and manual session management. `bwx` wraps it with:
 
 - **Auto-unlock** — first vault command authenticates automatically via macOS Keychain
-- **Session caching** — token written atomically as mode 600 to `~/.config/bwx/session`, passed to `bw` through `BW_SESSION` so it never appears in a process command line
+- **Session caching** — token written atomically as mode 600 to `~/.config/bwx/session`; concurrent callers share one bounded login/unlock attempt, and the token reaches `bw` through `BW_SESSION` rather than a process command line
 - **Structured output** — `--json` and `--plain` flags for machine-parseable output
 - **Leak-resistant** — listings never print secrets, `bwx run` hands them to a child process instead of stdout
 - **No interaction** — credentials from config + Keychain, never prompts
@@ -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.1",
   "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/session.ts

@@ -2,9 +2,16 @@ import { unlinkSync } from "node:fs";
 import { CliError, ExitCode } from "../cli/errors.ts";
 import type { GlobalOptions } from "../cli/types.ts";
 import { emitLog, emitWarn } from "../cli/io.ts";
-import { SESSION_FILE } from "../config/paths.ts";
+import { SESSION_FILE, SESSION_LOCK_DIR } from "../config/paths.ts";
+import { withProcessLock } from "../config/process-lock.ts";
 import { readPrivateFile, writePrivateFile } from "../config/secure-file.ts";
-import { runBw, runBwOrThrow, setSession, getSession } from "./runner.ts";
+import {
+	DEFAULT_TIMEOUT_MS,
+	runBw,
+	runBwOrThrow,
+	setSession,
+	getSession,
+} from "./runner.ts";
 import { checkVaultFreshness } from "./freshness.ts";
 import { getStatus } from "./status.ts";
 import { BwStatusSchema } from "./types.ts";
@@ -96,13 +103,36 @@ export async function probeSessionState(
 }
 
 export async function ensureUnlocked(opts: GlobalOptions): Promise<void> {
-	// Try cached session first
+	// Keep the ordinary valid-session path entirely outside the process lock.
 	const cached = getSession() || loadCachedSession(opts);
 	if (cached) {
 		setSession(cached);
 		if (await sessionWorks(cached)) return;
+		setSession(null);
 	}
 
+	await withProcessLock(
+		{
+			path: SESSION_LOCK_DIR,
+			label: "Bitwarden session establishment",
+			waitMs: sessionLockWaitMs(opts),
+		},
+		async () => {
+			// A process that waited must use the winner's disk cache, not the stale
+			// token it may still have held in memory before entering the lock.
+			const winner = loadCachedSession(opts);
+			if (winner) {
+				setSession(winner);
+				if (await sessionWorks(winner)) return;
+				setSession(null);
+			}
+
+			await establishSession(opts);
+		},
+	);
+}
+
+async function establishSession(opts: GlobalOptions): Promise<void> {
 	const status = await getStatus();
 
 	if (status.status === "unlocked") {
@@ -152,6 +182,13 @@ export async function ensureUnlocked(opts: GlobalOptions): Promise<void> {
 	saveCachedSession(token);
 }
 
+/** Four sequential `bw` calls cover stale validation plus status/login/unlock. */
+function sessionLockWaitMs(opts: GlobalOptions): number {
+	const perCall =
+		opts.timeoutMs && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+	return Math.min(Math.max(perCall * 4 + 10_000, 10_000), 5 * 60_000);
+}
+
 export async function lockVault(): Promise<void> {
 	await runBw(["lock"], { session: null });
 	setSession(null);
@@ -197,9 +234,9 @@ async function withAuthRetry<T>(
 		return await fn();
 	} catch (err) {
 		if (err instanceof CliError && err.exitCode === ExitCode.AuthFailed) {
-			// Clear stale session and re-auth
+			// Do not unlink the shared cache here: another process may already have
+			// atomically replaced our stale token with a freshly unlocked session.
 			setSession(null);
-			clearCachedSession();
 			await ensureUnlocked(opts);
 			return await fn();
 		}