bwx 0.3.0 → 0.4.1

package/src/bw/runner.ts

@@ -1,4 +1,5 @@
 import { CliError, ExitCode, classifyBwError } from "../cli/errors.ts";
+import { formatDuration } from "../cli/duration.ts";
 
 export interface BwResult {
 	stdout: string;
@@ -6,7 +7,20 @@ export interface BwResult {
 	exitCode: number;
 }
 
+export interface RunBwOptions {
+	/** Explicit session, or `null` to run without one (login/unlock/status). */
+	session?: string | null;
+	env?: Record<string, string>;
+}
+
+/** Deadline for a single `bw` call; overridable with `--timeout`. */
+export const DEFAULT_TIMEOUT_MS = 60_000;
+
+/** Grace period between SIGTERM and SIGKILL for a `bw` process past its deadline. */
+const KILL_GRACE_MS = 2_000;
+
 let sessionToken: string | null = null;
+let timeoutMs: number = DEFAULT_TIMEOUT_MS;
 
 export function setSession(token: string | null): void {
 	sessionToken = token;
@@ -16,33 +30,51 @@ export function getSession(): string | null {
 	return sessionToken;
 }
 
+/** Applies the `--timeout` value for the rest of the process. */
+export function setBwTimeout(ms: number): void {
+	timeoutMs = ms;
+}
+
 export async function runBw(
 	args: string[],
-	options?: { session?: string | null; env?: Record<string, string> },
+	options?: RunBwOptions,
 ): Promise<BwResult> {
 	const session = options?.session ?? sessionToken;
-	const fullArgs = session ? [...args, "--session", session] : args;
 
-	const proc = Bun.spawn(["bw", ...fullArgs], {
+	const proc = Bun.spawn(["bw", ...args], {
 		stdout: "pipe",
 		stderr: "pipe",
 		stdin: "ignore",
-		env: options?.env ? { ...process.env, ...options.env } : undefined,
+		// The session goes in the environment, never in argv: command lines are
+		// readable by any same-user process. Nothing here is ever logged.
+		env: buildEnv(session, options?.env),
 	});
 
-	const [stdout, stderr] = await Promise.all([
-		new Response(proc.stdout).text(),
-		new Response(proc.stderr).text(),
-	]);
+	const guard = timeoutMs > 0 ? armDeadline(proc, timeoutMs) : null;
+
+	try {
+		const [stdout, stderr] = await Promise.all([
+			new Response(proc.stdout).text(),
+			new Response(proc.stderr).text(),
+		]);
+		const exitCode = await proc.exited;
 
-	const exitCode = await proc.exited;
+		if (guard?.expired) {
+			throw new CliError(
+				`bw ${args[0] ?? ""} timed out after ${formatDuration(timeoutMs)}`.trim(),
+				ExitCode.Timeout,
+			);
+		}
 
-	return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
+		return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
+	} finally {
+		guard?.disarm();
+	}
 }
 
 export async function runBwOrThrow(
 	args: string[],
-	options?: { session?: string | null; env?: Record<string, string> },
+	options?: RunBwOptions,
 ): Promise<string> {
 	const result = await runBw(args, options);
 	if (result.exitCode !== 0) {
@@ -55,6 +87,70 @@ export async function runBwOrThrow(
 	return result.stdout;
 }
 
-export function isAuthError(result: BwResult): boolean {
-	return /not logged in|vault is locked|unauthenticated/i.test(result.stderr);
+/**
+ * Child environment for `bw`. `BW_SESSION` is set from our session, or removed
+ * outright so an ambient one from the caller's shell cannot silently substitute
+ * for it (`status`, `login`, and `unlock` rely on seeing the real vault state).
+ *
+ * `BW_NOINTERACTION` is mandatory: bwx runs `bw` with stdin ignored, so a prompt
+ * can only ever produce a hang or garbled output — a locked vault must fail
+ * loudly instead, which is what lets callers auto-unlock and retry.
+ */
+function buildEnv(
+	session: string | null,
+	extra?: Record<string, string>,
+): Record<string, string | undefined> {
+	const env: Record<string, string | undefined> = {
+		...process.env,
+		BW_NOINTERACTION: "true",
+		...extra,
+	};
+	if (session) {
+		env.BW_SESSION = session;
+	} else {
+		delete env.BW_SESSION;
+	}
+	return env;
+}
+
+interface Deadline {
+	expired: boolean;
+	disarm(): void;
+}
+
+/**
+ * Kills `bw` once the deadline passes so a wedged vault operation (stuck Keychain
+ * prompt, unreachable self-hosted server) cannot block the caller forever.
+ */
+function armDeadline(proc: Bun.Subprocess, ms: number): Deadline {
+	const timers: ReturnType<typeof setTimeout>[] = [];
+	const deadline: Deadline = {
+		expired: false,
+		disarm: () => timers.forEach(clearTimeout),
+	};
+
+	const arm = (delay: number, fn: () => void) => {
+		const timer = setTimeout(fn, delay);
+		timer.unref?.();
+		timers.push(timer);
+	};
+
+	// A timer can still fire in the moment between exit and disarm, where the
+	// signal has nowhere to go.
+	const kill = (signal: NodeJS.Signals) => {
+		try {
+			proc.kill(signal);
+		} catch {
+			// Already gone.
+		}
+	};
+
+	arm(ms, () => {
+		deadline.expired = true;
+		kill("SIGTERM");
+		// Escalate if bw ignores SIGTERM.
+		arm(KILL_GRACE_MS, () => kill("SIGKILL"));
+	});
+
+	return deadline;
 }

package/src/bw/session.ts

@@ -1,58 +1,41 @@
+import { unlinkSync } from "node:fs";
 import { CliError, ExitCode } from "../cli/errors.ts";
 import type { GlobalOptions } from "../cli/types.ts";
-import { emitLog } from "../cli/io.ts";
-import {
-	runBw,
-	runBwOrThrow,
-	setSession,
-	getSession,
-	isAuthError,
-	type BwResult,
-} from "./runner.ts";
-import { BwStatusSchema, type BwStatus } from "./types.ts";
+import { emitLog, emitWarn } from "../cli/io.ts";
+import { SESSION_FILE } from "../config/paths.ts";
+import { readPrivateFile, writePrivateFile } from "../config/secure-file.ts";
+import { runBw, runBwOrThrow, setSession, getSession } from "./runner.ts";
+import { checkVaultFreshness } from "./freshness.ts";
+import { getStatus } from "./status.ts";
+import { BwStatusSchema } from "./types.ts";
 import { loadConfig } from "../config/store.ts";
 
-const SESSION_PATH = `${process.env.HOME}/.config/bwx/session`;
-
-async function loadCachedSession(): Promise<string | null> {
-	try {
-		const token = await Bun.file(SESSION_PATH).text();
-		return token.trim() || null;
-	} catch {
+/**
+ * Loads the cached session, ignoring a cache file that another user could have
+ * planted or read. Rejection is not fatal: the caller just unlocks again.
+ */
+function loadCachedSession(opts: GlobalOptions): string | null {
+	const read = readPrivateFile(SESSION_FILE);
+	if (read.kind === "rejected") {
+		emitWarn(`Ignoring cached session: ${read.reason}`, opts);
 		return null;
 	}
+	if (read.kind === "missing") return null;
+	return read.text.trim() || null;
 }
 
-async function saveCachedSession(token: string): Promise<void> {
-	const dir = SESSION_PATH.replace(/\/[^/]+$/, "");
-	const { mkdirSync } = await import("node:fs");
-	mkdirSync(dir, { recursive: true });
-	await Bun.write(SESSION_PATH, token);
-	const proc = Bun.spawn(["chmod", "600", SESSION_PATH]);
-	await proc.exited;
+function saveCachedSession(token: string): void {
+	writePrivateFile(SESSION_FILE, token);
 }
 
-async function clearCachedSession(): Promise<void> {
+function clearCachedSession(): void {
 	try {
-		const { unlinkSync } = await import("node:fs");
-		unlinkSync(SESSION_PATH);
+		unlinkSync(SESSION_FILE);
 	} catch {
 		// Already gone
 	}
 }
 
-export async function getStatus(): Promise<BwStatus> {
-	const result = await runBw(["status"], { session: null });
-	try {
-		return BwStatusSchema.parse(JSON.parse(result.stdout));
-	} catch {
-		throw new CliError(
-			`Failed to parse bw status: ${result.stdout}`,
-			ExitCode.BwError,
-		);
-	}
-}
-
 async function getMasterPassword(): Promise<string> {
 	const proc = Bun.spawn(
 		[
@@ -77,11 +60,9 @@ async function getMasterPassword(): Promise<string> {
 	return pw;
 }
 
-export async function ensureUnlocked(
-	opts: GlobalOptions,
-): Promise<void> {
+export async function ensureUnlocked(opts: GlobalOptions): Promise<void> {
 	// Try cached session first
-	const cached = getSession() || (await loadCachedSession());
+	const cached = getSession() || loadCachedSession(opts);
 	if (cached) {
 		setSession(cached);
 		// Quick check — try a lightweight command
@@ -114,17 +95,9 @@ export async function ensureUnlocked(
 		const pw = await getMasterPassword();
 		emitLog("Logging in...", opts);
 		const loginResult = await runBw(
-			[
-				"login",
-				config.email,
-				"--passwordenv",
-				"BW_MASTER_PW",
-				"--quiet",
-			],
-			{
-				session: null,
-				env: { BW_MASTER_PW: pw, BW_NOINTERACTION: "true" },
-			},
+			["login", config.email, "--passwordenv", "BW_MASTER_PW", "--quiet"],
+			// BW_NOINTERACTION is set for every bw call by the runner.
+			{ session: null, env: { BW_MASTER_PW: pw } },
 		);
 		if (loginResult.exitCode !== 0) {
 			throw new CliError(
@@ -150,35 +123,57 @@ export async function ensureUnlocked(
 
 	const token = unlockResult.stdout;
 	setSession(token);
-	await saveCachedSession(token);
+	saveCachedSession(token);
 }
 
 export async function lockVault(): Promise<void> {
 	await runBw(["lock"], { session: null });
 	setSession(null);
-	await clearCachedSession();
+	clearCachedSession();
+}
+
+interface SessionOptions {
+	/**
+	 * Skips the stale-vault check. Set by operations that own vault freshness
+	 * themselves (`sync`) to avoid recursion.
+	 */
+	skipFreshnessCheck?: boolean;
 }
 
 export async function withSession<T>(
 	opts: GlobalOptions,
 	fn: () => Promise<T>,
+	options?: SessionOptions,
 ): Promise<T> {
 	// Try with current/cached session
-	const cached = getSession() || (await loadCachedSession());
+	const cached = getSession() || loadCachedSession(opts);
 	if (cached) {
 		setSession(cached);
 	}
 
+	if (!options?.skipFreshnessCheck) {
+		await checkVaultFreshness(opts, () => syncVault(opts));
+	}
+
+	return withAuthRetry(opts, fn);
+}
+
+async function syncVault(opts: GlobalOptions): Promise<void> {
+	await withAuthRetry(opts, () => runBwOrThrow(["sync"]));
+}
+
+/** Runs `fn`, re-authenticating once if the cached session turned out to be stale. */
+async function withAuthRetry<T>(
+	opts: GlobalOptions,
+	fn: () => Promise<T>,
+): Promise<T> {
 	try {
 		return await fn();
 	} catch (err) {
-		if (
-			err instanceof CliError &&
-			err.exitCode === ExitCode.AuthFailed
-		) {
+		if (err instanceof CliError && err.exitCode === ExitCode.AuthFailed) {
 			// Clear stale session and re-auth
 			setSession(null);
-			await clearCachedSession();
+			clearCachedSession();
 			await ensureUnlocked(opts);
 			return await fn();
 		}

package/src/bw/status.ts

@@ -0,0 +1,19 @@
+import { CliError, ExitCode } from "../cli/errors.ts";
+import { runBw } from "./runner.ts";
+import { BwStatusSchema, type BwStatus } from "./types.ts";
+
+/**
+ * Reads the vault state. Deliberately runs without a session so the result
+ * reflects the vault itself rather than our cached unlock.
+ */
+export async function getStatus(): Promise<BwStatus> {
+	const result = await runBw(["status"], { session: null });
+	try {
+		return BwStatusSchema.parse(JSON.parse(result.stdout));
+	} catch {
+		throw new CliError(
+			`Failed to parse bw status: ${result.stdout}`,
+			ExitCode.BwError,
+		);
+	}
+}

package/src/cli/commands/doctor.ts

@@ -2,6 +2,7 @@ import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { emitData } from "../io.ts";
 import { loadConfig } from "../../config/store.ts";
+import { CONFIG_DIR } from "../../config/paths.ts";
 import pc from "picocolors";
 
 interface Check {
@@ -140,9 +141,7 @@ async function checkMasterPassword(): Promise<Check> {
 }
 
 async function checkConfigDir(): Promise<Check> {
-	const configDir =
-		process.env.XDG_CONFIG_HOME ?? `${process.env.HOME}/.config`;
-	const dir = `${configDir}/bwx`;
+	const dir = CONFIG_DIR;
 	try {
 		const { accessSync, constants } = await import("node:fs");
 		accessSync(dir, constants.W_OK);

package/src/cli/commands/get.ts

@@ -1,13 +1,7 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { emitData } from "../io.ts";
-import { CliError, ExitCode } from "../errors.ts";
-import { runBwOrThrow } from "../../bw/runner.ts";
-import { withSession } from "../../bw/session.ts";
-import { BW_TYPE_LABELS, BwItemSchema } from "../../bw/types.ts";
-import pc from "picocolors";
-
-const BUILTIN_FIELDS = ["password", "username", "totp", "notes", "uri", "item"];
+import { readItemField } from "../../bw/fields.ts";
 
 export function registerGet(program: Command): void {
 	program
@@ -17,12 +11,9 @@ export function registerGet(program: Command): void {
 		.argument("<item>", "Item name or ID")
 		.action(async function (this: Command, field: string, item: string) {
 			const opts = getGlobalOpts(this);
-
-			if (BUILTIN_FIELDS.includes(field)) {
-				await getBuiltinField(field, item, opts);
-			} else {
-				await getCustomField(field, item, opts);
-			}
+			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);
 		});
 
 	program
@@ -32,121 +23,6 @@ export function registerGet(program: Command): void {
 		.argument("<name>", "Custom field name")
 		.action(async function (this: Command, item: string, name: string) {
 			const opts = getGlobalOpts(this);
-			await getCustomField(name, item, opts);
-		});
-}
-
-async function getBuiltinField(
-	field: string,
-	item: string,
-	opts: ReturnType<typeof getGlobalOpts>,
-): Promise<void> {
-	try {
-		const result = await withSession(opts, async () => {
-			if (field === "item") {
-				return runBwOrThrow(["get", "item", item]);
-			}
-			return runBwOrThrow(["get", field, item]);
+			emitData(await readItemField(name, item, opts, { customOnly: true }), opts);
 		});
-
-		if (!result) {
-			throw new CliError(
-				`No ${field} found for item: ${item}`,
-				ExitCode.NotFound,
-			);
-		}
-
-		if (field === "item") {
-			emitData(JSON.parse(result), opts);
-		} else {
-			emitData(result, opts);
-		}
-	} catch (err) {
-		if (
-			err instanceof CliError &&
-			/more than one result/i.test(err.message)
-		) {
-			const matches = await resolveAmbiguous(item);
-			throw new CliError(
-				formatAmbiguousError(item, matches, opts),
-				ExitCode.BadArgs,
-			);
-		}
-		throw err;
-	}
-}
-
-async function getCustomField(
-	fieldName: string,
-	item: string,
-	opts: ReturnType<typeof getGlobalOpts>,
-): Promise<void> {
-	const json = await withSession(opts, () =>
-		runBwOrThrow(["get", "item", item]),
-	);
-
-	const parsed = BwItemSchema.parse(JSON.parse(json));
-	const fields = parsed.fields ?? [];
-	const match = fields.find((f) => f.name === fieldName);
-
-	if (!match) {
-		const available = fields.map((f) => f.name).join(", ");
-		const msg = available
-			? `Field "${fieldName}" not found. Available: ${available}`
-			: `Field "${fieldName}" not found (item has no custom fields)`;
-		throw new CliError(msg, ExitCode.NotFound);
-	}
-
-	emitData(match.value ?? "", opts);
-}
-
-interface MatchInfo {
-	id: string;
-	name: string;
-	type: string;
-	username?: string;
-}
-
-async function resolveAmbiguous(query: string): Promise<MatchInfo[]> {
-	try {
-		const json = await runBwOrThrow([
-			"list",
-			"items",
-			"--search",
-			query,
-		]);
-		const items: Array<Record<string, unknown>> = JSON.parse(json);
-		return items.map((i) => ({
-			id: i.id as string,
-			name: i.name as string,
-			type: BW_TYPE_LABELS[i.type as number] ?? `type:${i.type}`,
-			username: (i.login as Record<string, unknown> | null)?.username as
-				| string
-				| undefined,
-		}));
-	} catch {
-		return [];
-	}
-}
-
-function formatAmbiguousError(
-	query: string,
-	matches: MatchInfo[],
-	opts: { json?: boolean },
-): string {
-	if (matches.length === 0) {
-		return `Multiple items match "${query}". Use a specific ID instead.`;
-	}
-
-	if (opts.json) {
-		return `Multiple items match "${query}": ${JSON.stringify(matches)}`;
-	}
-
-	const lines = [`Multiple items match "${query}":\n`];
-	for (const m of matches) {
-		const user = m.username ? ` (${m.username})` : "";
-		lines.push(`  ${pc.dim(m.id)}  ${pc.cyan(m.type)}  ${m.name}${pc.dim(user)}`);
-	}
-	lines.push(`\nUse a specific ID: ${pc.dim("bwx get <field> <id>")}`);
-	return lines.join("\n");
 }

package/src/cli/commands/list.ts

@@ -1,11 +1,9 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
-import { emitData } from "../io.ts";
 import { CliError, ExitCode } from "../errors.ts";
+import { filterItems, writeItems, type ItemListOptions } from "../items.ts";
 import { runBwOrThrow } from "../../bw/runner.ts";
 import { withSession } from "../../bw/session.ts";
-import { BW_TYPE_LABELS, BW_TYPE_FROM_NAME } from "../../bw/types.ts";
-import pc from "picocolors";
 
 export function registerList(program: Command): void {
 	program
@@ -15,10 +13,11 @@ export function registerList(program: Command): void {
 		.argument("[type]", "Filter by type: logins|notes|cards|identities")
 		.option("--folder <id>", "Filter by folder ID")
 		.option("--limit <n>", "Limit results", parseInt)
+		.option("--full-items", "Emit complete item objects (includes secrets)")
 		.action(async function (
 			this: Command,
 			type: string | undefined,
-			localOpts: { folder?: string; limit?: number },
+			localOpts: ItemListOptions & { folder?: string },
 		) {
 			const opts = getGlobalOpts(this);
 
@@ -28,54 +27,12 @@ export function registerList(program: Command): void {
 			}
 
 			const json = await withSession(opts, () => runBwOrThrow(args));
-			let items: Array<Record<string, unknown>> = JSON.parse(json);
-
-			if (type) {
-				const typeVal = BW_TYPE_FROM_NAME[type];
-				if (typeVal === undefined) {
-					throw new CliError(
-						`Invalid type "${type}". Valid: logins, notes, cards, identities`,
-						ExitCode.BadArgs,
-					);
-				}
-				items = items.filter((i) => i.type === typeVal);
-			}
-
-			if (localOpts.limit && localOpts.limit > 0) {
-				items = items.slice(0, localOpts.limit);
-			}
+			const items = filterItems(JSON.parse(json), { ...localOpts, type });
 
 			if (items.length === 0) {
 				throw new CliError("No items found", ExitCode.NotFound);
 			}
 
-			if (opts.json) {
-				emitData(items, opts);
-				return;
-			}
-
-			if (opts.plain) {
-				for (const item of items) {
-					const t =
-						BW_TYPE_LABELS[item.type as number] ?? `type:${item.type}`;
-					const login = item.login as Record<string, unknown> | null;
-					const username = login?.username ?? "-";
-					process.stdout.write(
-						`${item.id}\t${t}\t${item.name}\t${username}\n`,
-					);
-				}
-				return;
-			}
-
-			for (const item of items) {
-				const t =
-					BW_TYPE_LABELS[item.type as number] ?? `type:${item.type}`;
-				const login = item.login as Record<string, unknown> | null;
-				const username = login?.username ?? "";
-				const userPart = username ? pc.dim(` (${username})`) : "";
-				process.stdout.write(
-					`${pc.dim(item.id as string)}  ${pc.cyan(t)}  ${item.name}${userPart}\n`,
-				);
-			}
+			writeItems(items, opts, localOpts);
 		});
 }