bwx 0.3.0 → 0.4.0

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