bwx 0.6.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

package/package.json

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

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();
 		}

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`;

package/src/config/process-lock.ts

@@ -0,0 +1,255 @@
+import { randomUUID } from "node:crypto";
+import {
+	chmodSync,
+	lstatSync,
+	mkdirSync,
+	renameSync,
+	rmSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { CliError, ExitCode } from "../cli/errors.ts";
+import { formatDuration } from "../cli/duration.ts";
+import { readPrivateFile, writePrivateFile } from "./secure-file.ts";
+
+const OWNER_FILE = "owner.json";
+const DEFAULT_POLL_MS = 50;
+const SHARED_BITS = 0o077;
+const UUID_RE =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+interface LockOwner {
+	pid: number;
+	token: string;
+	acquiredAt: string;
+}
+
+interface ProcessLockOptions {
+	path: string;
+	label: string;
+	waitMs: number;
+	pollMs?: number;
+}
+
+interface Ownership {
+	path: string;
+	owner: LockOwner;
+}
+
+/**
+ * Runs a critical section under a cross-process lock. Publishing a populated
+ * directory by rename keeps contenders from observing a half-created lock;
+ * live owners are waited on, while dead-owner generations are safely detached.
+ */
+export async function withProcessLock<T>(
+	options: ProcessLockOptions,
+	fn: () => Promise<T>,
+): Promise<T> {
+	const ownership = await acquire(options);
+	let bodyFailed = false;
+
+	try {
+		return await fn();
+	} catch (err) {
+		bodyFailed = true;
+		throw err;
+	} finally {
+		try {
+			release(ownership, options.label);
+		} catch (err) {
+			// Preserve the operation's useful error if cleanup also failed.
+			if (!bodyFailed) throw err;
+		}
+	}
+}
+
+async function acquire(options: ProcessLockOptions): Promise<Ownership> {
+	const startedAt = performance.now();
+	let holder: LockOwner | null = null;
+
+	while (true) {
+		const ownership = tryCreate(options.path);
+		if (ownership) return ownership;
+
+		holder = readOwner(options.path, options.label);
+		if (!holder) continue;
+
+		if (!isProcessAlive(holder.pid)) {
+			if (detachAbandonedLock(options.path, holder, options.label)) continue;
+		}
+
+		const elapsed = performance.now() - startedAt;
+		if (elapsed >= options.waitMs) {
+			throw new CliError(
+				`Timed out after ${formatDuration(options.waitMs)} waiting for ${options.label} held by pid ${holder.pid}`,
+				ExitCode.Timeout,
+			);
+		}
+
+		const remaining = options.waitMs - elapsed;
+		await Bun.sleep(Math.min(options.pollMs ?? DEFAULT_POLL_MS, remaining));
+	}
+}
+
+function tryCreate(path: string): Ownership | null {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+
+	const owner: LockOwner = {
+		pid: process.pid,
+		token: randomUUID(),
+		acquiredAt: new Date().toISOString(),
+	};
+	const candidate = `${path}.${owner.token}.tmp`;
+
+	try {
+		mkdirSync(candidate, { mode: 0o700 });
+		chmodSync(candidate, 0o700);
+		writePrivateFile(
+			`${candidate}/${OWNER_FILE}`,
+			JSON.stringify(owner) + "\n",
+		);
+		try {
+			renameSync(candidate, path);
+			return { path, owner };
+		} catch (err) {
+			if (pathExists(path)) return null;
+			throw err;
+		}
+	} finally {
+		if (pathExists(candidate)) {
+			rmSync(candidate, { recursive: true, force: true });
+		}
+	}
+}
+
+function readOwner(path: string, label: string): LockOwner | null {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch (err) {
+		if (errorCode(err) === "ENOENT") return null;
+		throw err;
+	}
+
+	if (stat.isSymbolicLink() || !stat.isDirectory()) {
+		throw invalidLock(label, `${path} is not a regular directory`);
+	}
+	if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+		throw invalidLock(label, `${path} is owned by uid ${stat.uid}`);
+	}
+	if (stat.mode & SHARED_BITS) {
+		const mode = (stat.mode & 0o777).toString(8).padStart(3, "0");
+		throw invalidLock(label, `${path} has mode ${mode}, expected 700`);
+	}
+
+	const read = readPrivateFile(`${path}/${OWNER_FILE}`);
+	if (read.kind !== "ok") {
+		const reason =
+			read.kind === "missing"
+				? `${path}/${OWNER_FILE} is missing`
+				: read.reason;
+		throw invalidLock(label, reason);
+	}
+
+	try {
+		const owner = JSON.parse(read.text) as Partial<LockOwner>;
+		if (
+			!Number.isSafeInteger(owner.pid) ||
+			(owner.pid ?? 0) <= 0 ||
+			typeof owner.token !== "string" ||
+			!UUID_RE.test(owner.token) ||
+			typeof owner.acquiredAt !== "string" ||
+			!Number.isFinite(Date.parse(owner.acquiredAt))
+		) {
+			throw new Error("invalid owner fields");
+		}
+		return owner as LockOwner;
+	} catch {
+		throw invalidLock(label, `${path}/${OWNER_FILE} is malformed`);
+	}
+}
+
+function detachAbandonedLock(
+	path: string,
+	expected: LockOwner,
+	label: string,
+): boolean {
+	// The generation-specific recovery lock prevents two stale observations from
+	// detaching a successor that appeared between inspection and rename.
+	const recoveryPath = `${path}.reap.${expected.token}`;
+	const recovery = tryCreate(recoveryPath);
+	if (!recovery) {
+		const recoveryOwner = readOwner(recoveryPath, `${label} recovery lock`);
+		if (recoveryOwner && !isProcessAlive(recoveryOwner.pid)) {
+			detachAbandonedLock(
+				recoveryPath,
+				recoveryOwner,
+				`${label} recovery lock`,
+			);
+		}
+		return false;
+	}
+
+	let abandoned: string | null = null;
+	try {
+		const current = readOwner(path, label);
+		if (
+			!current ||
+			current.token !== expected.token ||
+			isProcessAlive(current.pid)
+		) {
+			return false;
+		}
+
+		abandoned = `${path}.${expected.token}.abandoned`;
+		try {
+			renameSync(path, abandoned);
+		} catch (err) {
+			if (errorCode(err) === "ENOENT") return false;
+			throw err;
+		}
+
+		// Cleanup names the detached generation, never a successor at the lock path.
+		rmSync(abandoned, { recursive: true, force: true });
+		return true;
+	} finally {
+		release(recovery, `${label} recovery lock`);
+	}
+}
+
+function release(ownership: Ownership, label: string): void {
+	const current = readOwner(ownership.path, label);
+	if (!current || current.token !== ownership.owner.token) {
+		throw invalidLock(label, "ownership changed before release");
+	}
+
+	const released = `${ownership.path}.${ownership.owner.token}.released`;
+	renameSync(ownership.path, released);
+	rmSync(released, { recursive: true, force: true });
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return errorCode(err) !== "ESRCH";
+	}
+}
+
+function pathExists(path: string): boolean {
+	try {
+		lstatSync(path);
+		return true;
+	} catch (err) {
+		if (errorCode(err) === "ENOENT") return false;
+		throw err;
+	}
+}
+
+function errorCode(err: unknown): string | undefined {
+	return (err as NodeJS.ErrnoException)?.code;
+}
+
+function invalidLock(label: string, reason: string): CliError {
+	return new CliError(`Unsafe or corrupt ${label}: ${reason}`, ExitCode.Config);
+}