bwx 0.3.0 → 0.4.1

package/src/cli/commands/run.ts

@@ -0,0 +1,138 @@
+import type { Command } from "commander";
+import { constants } from "node:os";
+import { readItemField } from "../../bw/fields.ts";
+import { CliError, ExitCode } from "../errors.ts";
+import { collect } from "../input.ts";
+import { emitLog } from "../io.ts";
+import { getGlobalOpts } from "../program.ts";
+import type { GlobalOptions } from "../types.ts";
+
+/** `NAME=<field>:<item>` — one secret to place in the child's environment. */
+export interface EnvSpec {
+	name: string;
+	field: string;
+	item: string;
+}
+
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const SPEC_HINT = "Expected --env NAME=<field>:<item>, e.g. --env DB_PASS=password:'Prod DB'";
+
+export function registerRun(program: Command): void {
+	program
+		.command("run")
+		.description("Run a command with secrets injected into its environment")
+		.argument("<command...>", "Command to run — use -- before it if it takes its own flags")
+		.option(
+			"--env <spec>",
+			"Inject a secret as NAME=<field>:<item> (repeatable)",
+			collect,
+			[],
+		)
+		.action(async function (
+			this: Command,
+			command: string[],
+			localOpts: { env: string[] },
+		) {
+			const opts = getGlobalOpts(this);
+			const specs = parseEnvSpecs(localOpts.env);
+
+			const secrets = await resolveSecrets(specs, opts);
+
+			// Only the names are ever logged; values exist solely in the child env.
+			if (opts.verbose) {
+				emitLog(`Injecting ${specs.map((s) => s.name).join(", ")}`, opts);
+			}
+
+			process.exit(await spawnChild(command, secrets));
+		});
+}
+
+/** Parses every `--env` flag, rejecting bad specs before any vault access. */
+export function parseEnvSpecs(raws: string[]): EnvSpec[] {
+	if (raws.length === 0) {
+		throw new CliError(`No secrets requested. ${SPEC_HINT}`, ExitCode.BadArgs);
+	}
+
+	const specs = raws.map(parseEnvSpec);
+
+	const seen = new Set<string>();
+	for (const spec of specs) {
+		if (seen.has(spec.name)) {
+			throw new CliError(`Duplicate --env name "${spec.name}"`, ExitCode.BadArgs);
+		}
+		seen.add(spec.name);
+	}
+
+	return specs;
+}
+
+/**
+ * Splits `NAME=<field>:<item>` on the first `=` and then the first `:`, so item
+ * names may contain colons (`password:http://my.router`) while field names may not.
+ * Fields resolve exactly as in `bwx get`: built-ins first, otherwise custom fields.
+ */
+export function parseEnvSpec(raw: string): EnvSpec {
+	const eq = raw.indexOf("=");
+	if (eq <= 0) {
+		throw new CliError(`Invalid --env "${raw}". ${SPEC_HINT}`, ExitCode.BadArgs);
+	}
+
+	const name = raw.slice(0, eq);
+	if (!ENV_NAME_RE.test(name)) {
+		throw new CliError(
+			`Invalid environment variable name "${name}". Use letters, digits, and underscores.`,
+			ExitCode.BadArgs,
+		);
+	}
+
+	const ref = raw.slice(eq + 1);
+	const colon = ref.indexOf(":");
+	if (colon <= 0 || colon === ref.length - 1) {
+		throw new CliError(`Invalid --env "${raw}". ${SPEC_HINT}`, ExitCode.BadArgs);
+	}
+
+	return { name, field: ref.slice(0, colon), item: ref.slice(colon + 1) };
+}
+
+/** Resolves secrets one at a time: each read spawns `bw`, and unlocks must not race. */
+async function resolveSecrets(
+	specs: EnvSpec[],
+	opts: GlobalOptions,
+): Promise<Record<string, string>> {
+	const secrets: Record<string, string> = {};
+
+	for (const spec of specs) {
+		secrets[spec.name] = await readItemField(spec.field, spec.item, opts);
+	}
+
+	return secrets;
+}
+
+/**
+ * Runs the child with inherited stdio so it stays usable interactively, and
+ * mirrors its exit status (`128 + signal` when it was killed, as shells do).
+ */
+async function spawnChild(
+	command: string[],
+	secrets: Record<string, string>,
+): Promise<number> {
+	let proc;
+	try {
+		proc = Bun.spawn(command, {
+			stdin: "inherit",
+			stdout: "inherit",
+			stderr: "inherit",
+			env: { ...process.env, ...secrets },
+		});
+	} catch (err) {
+		throw new CliError(
+			`Failed to run "${command[0]}": ${err instanceof Error ? err.message : String(err)}`,
+			ExitCode.BadArgs,
+		);
+	}
+
+	const exitCode = await proc.exited;
+	const signal = proc.signalCode;
+	return signal ? 128 + constants.signals[signal] : exitCode;
+}

package/src/cli/commands/search.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 registerSearch(program: Command): void {
 	program
@@ -15,10 +13,11 @@ export function registerSearch(program: Command): void {
 		.option("--type <type>", "Filter by type: login|note|card|identity")
 		.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,
 			query: string,
-			localOpts: { type?: string; folder?: string; limit?: number },
+			localOpts: ItemListOptions & { folder?: string },
 		) {
 			const opts = getGlobalOpts(this);
 
@@ -28,24 +27,7 @@ export function registerSearch(program: Command): void {
 			}
 
 			const json = await withSession(opts, () => runBwOrThrow(args));
-			let items: Array<Record<string, unknown>> = JSON.parse(json);
-
-			// Filter by type
-			if (localOpts.type) {
-				const typeVal = BW_TYPE_FROM_NAME[localOpts.type];
-				if (typeVal === undefined) {
-					throw new CliError(
-						`Invalid type "${localOpts.type}". Valid: login, note, card, identity`,
-						ExitCode.BadArgs,
-					);
-				}
-				items = items.filter((i) => i.type === typeVal);
-			}
-
-			// Limit
-			if (localOpts.limit && localOpts.limit > 0) {
-				items = items.slice(0, localOpts.limit);
-			}
+			const items = filterItems(JSON.parse(json), localOpts);
 
 			if (items.length === 0) {
 				throw new CliError(
@@ -54,32 +36,6 @@ export function registerSearch(program: Command): void {
 				);
 			}
 
-			if (opts.json) {
-				emitData(items, opts);
-				return;
-			}
-
-			if (opts.plain) {
-				for (const item of items) {
-					const type = 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${type}\t${item.name}\t${username}\n`,
-					);
-				}
-				return;
-			}
-
-			// Human-friendly table
-			for (const item of items) {
-				const type = 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(type)}  ${item.name}${userPart}\n`,
-				);
-			}
+			writeItems(items, opts, localOpts);
 		});
 }

package/src/cli/commands/status.ts

@@ -1,8 +1,8 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { emitData } from "../io.ts";
-import { getStatus } from "../../bw/session.ts";
-import { BW_TYPE_LABELS } from "../../bw/types.ts";
+import { recordStatus } from "../../bw/freshness.ts";
+import { getStatus } from "../../bw/status.ts";
 import pc from "picocolors";
 
 export function registerStatus(program: Command): void {
@@ -12,6 +12,8 @@ export function registerStatus(program: Command): void {
 		.action(async function (this: Command) {
 			const opts = getGlobalOpts(this);
 			const status = await getStatus();
+			// Reads reuse this for their staleness check instead of paying for `bw status`.
+			recordStatus(status);
 
 			if (opts.json || opts.plain) {
 				emitData(status, opts);

package/src/cli/commands/sync.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { emitSuccess } from "../io.ts";
+import { recordSyncNow } from "../../bw/freshness.ts";
 import { runBwOrThrow } from "../../bw/runner.ts";
 import { withSession } from "../../bw/session.ts";
 
@@ -10,7 +11,11 @@ export function registerSync(program: Command): void {
 		.description("Sync vault (auto-unlocks)")
 		.action(async function (this: Command) {
 			const opts = getGlobalOpts(this);
-			await withSession(opts, () => runBwOrThrow(["sync"]));
+			// This *is* the freshness fix — checking freshness first would be circular.
+			await withSession(opts, () => runBwOrThrow(["sync"]), {
+				skipFreshnessCheck: true,
+			});
+			recordSyncNow();
 			emitSuccess("Vault synced", opts);
 		});
 }

package/src/cli/duration.ts

@@ -0,0 +1,34 @@
+import { CliError, ExitCode } from "./errors.ts";
+
+const UNIT_MS: Record<string, number> = {
+	ms: 1,
+	s: 1_000,
+	m: 60_000,
+	h: 3_600_000,
+	d: 86_400_000,
+};
+
+const DURATION_RE = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/;
+
+/** Parses `250ms`, `30s`, `15m`, `2h`, `1d`. A bare number is seconds. */
+export function parseDuration(raw: string, flag: string): number {
+	const match = DURATION_RE.exec(raw.trim());
+	if (!match) {
+		throw new CliError(
+			`Invalid duration "${raw}" for ${flag}. Use e.g. 30s, 15m, 2h`,
+			ExitCode.BadArgs,
+		);
+	}
+	return Math.round(Number(match[1]) * UNIT_MS[match[2] ?? "s"]!);
+}
+
+/** Coarse human-readable duration for diagnostics: `45s`, `12m`, `3h`, `8d`. */
+export function formatDuration(ms: number): string {
+	const seconds = Math.max(0, Math.round(ms / 1000));
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.round(seconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.round(minutes / 60);
+	if (hours < 48) return `${hours}h`;
+	return `${Math.round(hours / 24)}d`;
+}

package/src/cli/io.ts

@@ -34,8 +34,14 @@ export function emitSuccess(message: string, opts: GlobalOptions): void {
 	process.stderr.write(pc.green("✓") + " " + message + "\n");
 }
 
+/**
+ * Warnings say the returned data may be wrong (stale vault, rejected session
+ * cache), so unlike logs they survive `--json` — the machine-readable callers are
+ * the ones that most need to hear it. Still stderr-only, so stdout stays
+ * parseable; `-q` is the way to silence them.
+ */
 export function emitWarn(message: string, opts: GlobalOptions): void {
-	if (opts.quiet || opts.json) return;
+	if (opts.quiet) return;
 	process.stderr.write(pc.yellow("⚠") + " " + message + "\n");
 }
 

package/src/cli/items.ts

@@ -0,0 +1,78 @@
+import pc from "picocolors";
+import { summarizeItem, type ItemSummary } from "../bw/items.ts";
+import { BW_TYPE_FROM_NAME } from "../bw/types.ts";
+import { CliError, ExitCode } from "./errors.ts";
+import { emitData } from "./io.ts";
+import type { GlobalOptions } from "./types.ts";
+
+export interface ItemListOptions {
+	type?: string;
+	limit?: number;
+	/** Opt in to raw bw items, which carry passwords, notes, and custom fields. */
+	fullItems?: boolean;
+}
+
+export function filterItems(
+	items: Array<Record<string, unknown>>,
+	options: ItemListOptions,
+): Array<Record<string, unknown>> {
+	let result = items;
+
+	if (options.type) {
+		const typeVal = BW_TYPE_FROM_NAME[options.type];
+		if (typeVal === undefined) {
+			throw new CliError(
+				`Invalid type "${options.type}". Valid: login, note, card, identity (plural forms accepted)`,
+				ExitCode.BadArgs,
+			);
+		}
+		result = result.filter((item) => item.type === typeVal);
+	}
+
+	if (options.limit && options.limit > 0) {
+		result = result.slice(0, options.limit);
+	}
+
+	return result;
+}
+
+/**
+ * Prints a set of vault items. Human, `--plain`, and `--json` output all carry
+ * the same reduced projection, so asking for machine-readable output is a
+ * serialization choice and never widens data access. `--full-items` is the
+ * explicit opt-in for callers that genuinely need the complete objects.
+ */
+export function writeItems(
+	items: Array<Record<string, unknown>>,
+	opts: GlobalOptions,
+	options: ItemListOptions = {},
+): void {
+	if (opts.json) {
+		emitData(options.fullItems ? items : items.map(summarizeItem), opts);
+		return;
+	}
+
+	if (options.fullItems) {
+		// Plain output stays line-oriented: one compact item per line (NDJSON).
+		if (opts.plain) writeLines(items, (item) => JSON.stringify(item));
+		else emitData(items, opts);
+		return;
+	}
+
+	writeLines(items.map(summarizeItem), opts.plain ? plainLine : humanLine);
+}
+
+function plainLine(summary: ItemSummary): string {
+	return `${summary.id}\t${summary.type}\t${summary.name}\t${summary.username ?? "-"}`;
+}
+
+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}`;
+}
+
+function writeLines<T>(values: T[], format: (value: T) => string): void {
+	for (const value of values) {
+		process.stdout.write(format(value) + "\n");
+	}
+}

package/src/cli/program.ts

@@ -1,4 +1,7 @@
 import { Command } from "commander";
+import pkg from "../../package.json" with { type: "json" };
+import { DEFAULT_TIMEOUT_MS, setBwTimeout } from "../bw/runner.ts";
+import { formatDuration, parseDuration } from "./duration.ts";
 import type { GlobalOptions } from "./types.ts";
 import { registerGet } from "./commands/get.ts";
 import { registerSearch } from "./commands/search.ts";
@@ -13,6 +16,7 @@ import { registerConfig } from "./commands/config.ts";
 import { registerDoctor } from "./commands/doctor.ts";
 import { registerList } from "./commands/list.ts";
 import { registerAttach } from "./commands/attach.ts";
+import { registerRun } from "./commands/run.ts";
 
 export function buildProgram(): Command {
 	const program = new Command();
@@ -20,15 +24,29 @@ export function buildProgram(): Command {
 	program
 		.name("bwx")
 		.description("Bitwarden Extended CLI")
-		.version("0.3.0")
+		.version(pkg.version)
 		.option("--json", "JSON output")
 		.option("--plain", "Plain parseable output")
 		.option("-q, --quiet", "Suppress log output")
 		.option("-v, --verbose", "Verbose output")
+		.option(
+			"--timeout <duration>",
+			"Deadline for each bw call, 0 to disable",
+			formatDuration(DEFAULT_TIMEOUT_MS),
+		)
+		.option(
+			"--sync-if-older-than <duration>",
+			"Sync first when the vault last synced longer ago than this",
+		)
 		.exitOverride()
 		.configureOutput({
 			writeOut: (str) => process.stdout.write(str),
 			writeErr: () => {}, // silenced — we handle all errors in main()
+		})
+		// Global options that configure the runtime are applied once, before any
+		// command action runs.
+		.hook("preAction", (_program, actionCommand) => {
+			setBwTimeout(getGlobalOpts(actionCommand).timeoutMs ?? DEFAULT_TIMEOUT_MS);
 		});
 
 	registerStatus(program);
@@ -36,6 +54,7 @@ export function buildProgram(): Command {
 	registerLock(program);
 	registerGet(program);
 	registerSearch(program);
+	registerRun(program);
 	registerSync(program);
 	registerCreate(program);
 	registerEdit(program);
@@ -55,5 +74,17 @@ export function getGlobalOpts(cmd: Command): GlobalOptions {
 		plain: root.plain ?? false,
 		quiet: root.quiet ?? false,
 		verbose: root.verbose ?? false,
+		timeoutMs: optionalDuration(root.timeout, "--timeout") ?? DEFAULT_TIMEOUT_MS,
+		syncIfOlderThanMs: optionalDuration(
+			root.syncIfOlderThan,
+			"--sync-if-older-than",
+		),
 	};
 }
+
+function optionalDuration(
+	raw: string | undefined,
+	flag: string,
+): number | undefined {
+	return raw === undefined ? undefined : parseDuration(raw, flag);
+}

package/src/cli/types.ts

@@ -3,8 +3,11 @@ export interface GlobalOptions {
 	plain?: boolean;
 	quiet?: boolean;
 	verbose?: boolean;
-}
-
-export interface CliContext {
-	opts: GlobalOptions;
+	/** Deadline for each `bw` call in ms; `0` disables it. */
+	timeoutMs?: number;
+	/**
+	 * Sync before vault access when the last sync is older than this, in ms.
+	 * Undefined means "only warn about a stale vault".
+	 */
+	syncIfOlderThanMs?: number;
 }

package/src/config/paths.ts

@@ -0,0 +1,12 @@
+// All bwx state lives in one XDG-respecting directory so config, session, and
+// freshness state can never drift apart.
+
+const CONFIG_HOME =
+	process.env.XDG_CONFIG_HOME ?? `${process.env.HOME}/.config`;
+
+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`;
+/** Cached vault-freshness snapshot — see bw/freshness.ts. */
+export const STATE_FILE = `${CONFIG_DIR}/state.json`;

package/src/config/secure-file.ts

@@ -0,0 +1,83 @@
+import {
+	chmodSync,
+	lstatSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+const PRIVATE_FILE_MODE = 0o600;
+const PRIVATE_DIR_MODE = 0o700;
+/** Group/other permission bits — none of them may be set on a private file. */
+const SHARED_BITS = 0o077;
+
+export type PrivateFileRead =
+	| { kind: "ok"; text: string }
+	| { kind: "missing" }
+	| { kind: "rejected"; reason: string };
+
+/**
+ * Writes owner-only data atomically: a temp file in the destination directory is
+ * created with mode 0600 and then renamed over the target. Unlike write-then-chmod
+ * there is no window in which the payload is readable by others, and a crash leaves
+ * either the old file or the new one — never a permissive partial write.
+ */
+export function writePrivateFile(path: string, contents: string): void {
+	mkdirSync(dirname(path), { recursive: true, mode: PRIVATE_DIR_MODE });
+
+	const tmp = `${path}.${process.pid}.tmp`;
+	try {
+		writeFileSync(tmp, contents, { mode: PRIVATE_FILE_MODE });
+		// writeFileSync's mode is subject to umask; chmod makes it exact.
+		chmodSync(tmp, PRIVATE_FILE_MODE);
+		renameSync(tmp, path);
+	} catch (err) {
+		try {
+			unlinkSync(tmp);
+		} catch {
+			// Nothing to clean up.
+		}
+		throw err;
+	}
+}
+
+/**
+ * Reads a file that is only trustworthy when it is a regular, owner-only file.
+ * A symlink, foreign owner, or any group/other permission bit means someone else
+ * could have planted or read the contents, so it is reported as rejected rather
+ * than returned — callers fall back to acquiring the data again.
+ */
+export function readPrivateFile(path: string): PrivateFileRead {
+	let stat;
+	try {
+		stat = lstatSync(path);
+	} catch {
+		return { kind: "missing" };
+	}
+
+	if (stat.isSymbolicLink()) {
+		return { kind: "rejected", reason: `${path} is a symlink` };
+	}
+	if (!stat.isFile()) {
+		return { kind: "rejected", reason: `${path} is not a regular file` };
+	}
+	if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+		return { kind: "rejected", reason: `${path} is owned by uid ${stat.uid}` };
+	}
+	if (stat.mode & SHARED_BITS) {
+		const mode = (stat.mode & 0o777).toString(8).padStart(3, "0");
+		return { kind: "rejected", reason: `${path} has mode ${mode}, expected 600` };
+	}
+
+	try {
+		return { kind: "ok", text: readFileSync(path, "utf8") };
+	} catch (err) {
+		return {
+			kind: "rejected",
+			reason: `${path} could not be read: ${err instanceof Error ? err.message : String(err)}`,
+		};
+	}
+}

package/src/config/store.ts

@@ -1,16 +1,14 @@
+import { mkdirSync } from "node:fs";
+import { CONFIG_DIR, CONFIG_FILE } from "./paths.ts";
 import { ConfigSchema, type Config } from "./schema.ts";
 
-const CONFIG_DIR =
-	process.env.XDG_CONFIG_HOME ?? `${process.env.HOME}/.config`;
-const CONFIG_PATH = `${CONFIG_DIR}/bwx/config.json`;
-
 export function getConfigPath(): string {
-	return CONFIG_PATH;
+	return CONFIG_FILE;
 }
 
 export async function loadConfig(): Promise<Config> {
 	try {
-		const text = await Bun.file(CONFIG_PATH).text();
+		const text = await Bun.file(CONFIG_FILE).text();
 		return ConfigSchema.parse(JSON.parse(text));
 	} catch {
 		return ConfigSchema.parse({});
@@ -18,8 +16,6 @@ export async function loadConfig(): Promise<Config> {
 }
 
 export async function saveConfig(config: Config): Promise<void> {
-	const dir = CONFIG_PATH.replace(/\/[^/]+$/, "");
-	const { mkdirSync } = await import("node:fs");
-	mkdirSync(dir, { recursive: true });
-	await Bun.write(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+	mkdirSync(CONFIG_DIR, { recursive: true });
+	await Bun.write(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n");
 }