bwx 0.3.0 → 0.4.0

package/README.md

@@ -17,9 +17,11 @@ 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 persisted to `~/.config/bwx/session` (mode 600), reused across calls
+- **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
 - **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
+- **Bounded** — every `bw` call has a deadline, so a wedged vault operation cannot hang a caller
 
 ## Install
 
@@ -64,10 +66,47 @@ bwx doctor
 |---------|-------------|
 | `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`) |
 | `bwx field <item> <name>` | Get custom field by name |
-| `bwx search <query>` | Search items (`--type`, `--folder`, `--limit`) |
+| `bwx search <query>` | Search items (`--type`, `--folder`, `--limit`, `--full-items`) |
+| `bwx list [type]` | List items (`--folder`, `--limit`, `--full-items`) |
+| `bwx run --env NAME=<field>:<item> -- <cmd>` | Run a command with secrets in its environment |
 | `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.
+
+### Secrets into a child process
+
+`bwx run` resolves secrets and places them only in the child's environment: nothing is
+printed to stdout, and nothing lands in a command line where other processes could read it.
+
+```bash
+bwx run --env KEENETIC_PASS=password:'http://my.keenetic.net' -- expect ./recovery.exp
+bwx run --env DB_PASS=password:'Prod DB' --env TOKEN='API Key:Acme' -- ./deploy.sh
+```
+
+- `--env NAME=<field>:<item>` is repeatable; the field resolves exactly as in `bwx get`
+  (built-ins first, otherwise a custom field name).
+- The item may contain colons — only the first one separates field from item.
+- Use `--` before the command whenever it takes its own flags.
+- The child inherits stdio and bwx exits with the child's status (`128 + signal` when killed).
+- `-v` logs the injected variable *names*; values are never logged.
+
+### Vault freshness
+
+`bw` answers reads from the local vault copy, so a vault that has not synced in a while
+returns stale secrets. Reads warn on stderr when the last sync is over 24h old, and
+`--sync-if-older-than <duration>` syncs first instead of warning:
+
+```bash
+bwx get password "Router"                          # warns if the vault is stale
+bwx --sync-if-older-than 15m get password "Router" # syncs first when needed
+```
+
+The check is cached in `~/.config/bwx/state.json`, so a fresh vault costs no extra `bw` call.
+
 ### Write
 
 | Command | Description |
@@ -119,8 +158,15 @@ Supported source flags:
 |------|--------|
 | `--json` | JSON output: `{ "data": ... }` / `{ "error": ... }` |
 | `--plain` | Tab-separated, one item per line |
-| `-q, --quiet` | Suppress logs |
+| `-q, --quiet` | Suppress logs and warnings |
 | `-v, --verbose` | Include stack traces |
+| `--timeout <duration>` | Deadline for each `bw` call (default `1m`, `0` disables) |
+| `--sync-if-older-than <duration>` | Sync before vault access when the last sync is older |
+
+Durations accept `250ms`, `30s`, `15m`, `2h`, `1d`; a bare number means seconds.
+
+Warnings ("vault is stale", "ignoring cached session") go to stderr even under `--json`,
+because they say the returned data may be wrong. `-q` silences them.
 
 ## Custom fields
 

package/package.json

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

package/src/bw/fields.ts

@@ -0,0 +1,133 @@
+import pc from "picocolors";
+import { CliError, ExitCode } from "../cli/errors.ts";
+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 { BwItemSchema } from "./types.ts";
+
+/** Fields `bw get` resolves natively; anything else is a custom field name. */
+const BUILTIN_FIELDS = [
+	"password",
+	"username",
+	"totp",
+	"notes",
+	"uri",
+	"item",
+] as const;
+
+function isBuiltinField(field: string): boolean {
+	return (BUILTIN_FIELDS as readonly string[]).includes(field);
+}
+
+export interface ReadFieldOptions {
+	/**
+	 * Always resolve `field` as a custom field name, so an item whose custom
+	 * field is called e.g. `password` is still reachable.
+	 */
+	customOnly?: boolean;
+}
+
+/**
+ * Reads one field from a vault item and returns it verbatim (`item` yields the
+ * item JSON), leaving the caller to decide whether the value is printed at all.
+ * Ambiguous item lookups fail with the candidate list instead of a raw bw error.
+ */
+export async function readItemField(
+	field: string,
+	item: string,
+	opts: GlobalOptions,
+	options?: ReadFieldOptions,
+): Promise<string> {
+	try {
+		return isBuiltinField(field) && !options?.customOnly
+			? await readBuiltinField(field, item, opts)
+			: await readCustomField(field, item, opts);
+	} catch (err) {
+		if (err instanceof CliError && /more than one result/i.test(err.message)) {
+			const matches = await findMatches(item);
+			throw new CliError(
+				formatAmbiguousError(item, matches, opts),
+				ExitCode.BadArgs,
+			);
+		}
+		throw err;
+	}
+}
+
+async function readBuiltinField(
+	field: string,
+	item: string,
+	opts: GlobalOptions,
+): Promise<string> {
+	const result = await withSession(opts, () =>
+		runBwOrThrow(["get", field, item]),
+	);
+
+	if (!result) {
+		throw new CliError(
+			`No ${field} found for item: ${item}`,
+			ExitCode.NotFound,
+		);
+	}
+
+	return result;
+}
+
+async function readCustomField(
+	fieldName: string,
+	item: string,
+	opts: GlobalOptions,
+): Promise<string> {
+	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);
+	}
+
+	return match.value ?? "";
+}
+
+async function findMatches(query: string): Promise<ItemSummary[]> {
+	try {
+		const json = await runBwOrThrow(["list", "items", "--search", query]);
+		const items: Array<Record<string, unknown>> = JSON.parse(json);
+		return items.map(summarizeItem);
+	} catch {
+		return [];
+	}
+}
+
+function formatAmbiguousError(
+	query: string,
+	matches: ItemSummary[],
+	opts: GlobalOptions,
+): 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/bw/freshness.ts

@@ -0,0 +1,161 @@
+import { formatDuration } from "../cli/duration.ts";
+import { emitLog, emitWarn } from "../cli/io.ts";
+import type { GlobalOptions } from "../cli/types.ts";
+import { STATE_FILE } from "../config/paths.ts";
+import { readPrivateFile, writePrivateFile } from "../config/secure-file.ts";
+import { getStatus } from "./status.ts";
+import type { BwStatus } from "./types.ts";
+
+/**
+ * `bw` serves reads from the local vault copy, so a vault that has not synced in
+ * days silently returns rotated-away secrets. Reads therefore check freshness —
+ * but `bw status` costs a full `bw` spawn (~2s), far too much to pay on every
+ * read, so the answer is cached here and only re-polled when it might matter.
+ */
+
+/** Warn when the vault has not synced within this window. */
+export const STALE_AFTER_MS = 24 * 60 * 60 * 1_000;
+
+/** While the vault looks stale, ask `bw status` again at most this often. */
+const RECHECK_INTERVAL_MS = 5 * 60 * 1_000;
+
+export interface FreshnessSnapshot {
+	/** `lastSync` as reported by `bw status`; null when the vault never synced. */
+	lastSync: string | null;
+	/** When bwx last asked `bw status` for that value. */
+	checkedAt: string;
+}
+
+export type FreshnessPlan =
+	/** Known fresh — no `bw` call, no warning. */
+	| "skip"
+	/** Known stale recently enough to trust the cached answer. */
+	| "stale"
+	/** Cached answer is missing, unusable, or too old to trust. */
+	| "poll";
+
+/**
+ * Decides what can be concluded from the cached snapshot alone. Pure so the
+ * caching policy stays testable without a vault.
+ */
+export function planFreshnessCheck(
+	snapshot: FreshnessSnapshot | null,
+	thresholdMs: number,
+	now: number,
+): FreshnessPlan {
+	if (!snapshot) return "poll";
+
+	if (isFresh(snapshot, thresholdMs, now)) return "skip";
+
+	const checkedAgeMs = now - Date.parse(snapshot.checkedAt);
+	const checkedRecently =
+		Number.isFinite(checkedAgeMs) &&
+		checkedAgeMs >= 0 &&
+		checkedAgeMs < RECHECK_INTERVAL_MS;
+
+	// lastSync only ever moves forward, so a stale reading stays stale unless
+	// another client synced — worth re-checking, just not on every read.
+	return checkedRecently ? "stale" : "poll";
+}
+
+/**
+ * Warns (or syncs, with `--sync-if-older-than`) when the local vault is stale.
+ * Advisory only: any failure to determine freshness is ignored rather than
+ * failing the operation the caller actually asked for.
+ */
+export async function checkVaultFreshness(
+	opts: GlobalOptions,
+	sync: () => Promise<unknown>,
+): Promise<void> {
+	const syncOnStale = opts.syncIfOlderThanMs !== undefined;
+	const thresholdMs = opts.syncIfOlderThanMs ?? STALE_AFTER_MS;
+
+	let snapshot = loadSnapshot();
+	const plan = planFreshnessCheck(snapshot, thresholdMs, Date.now());
+	if (plan === "skip") return;
+
+	if (plan === "poll") {
+		try {
+			snapshot = recordStatus(await getStatus());
+		} catch {
+			return; // Freshness is advisory — never block the real operation.
+		}
+		if (isFresh(snapshot, thresholdMs, Date.now())) return;
+	}
+
+	const ageMs = snapshotAgeMs(snapshot, Date.now());
+	const age = ageMs === null ? "never" : `${formatDuration(ageMs)} ago`;
+
+	if (!syncOnStale) {
+		emitWarn(
+			`Vault last synced ${age} — reads may be stale. Run 'bwx sync' or pass --sync-if-older-than <duration>.`,
+			opts,
+		);
+		return;
+	}
+
+	emitLog(`Vault last synced ${age} — syncing...`, opts);
+	await sync();
+	recordSyncNow();
+}
+
+/** Caches what `bw status` just reported. */
+export function recordStatus(status: BwStatus): FreshnessSnapshot {
+	return saveSnapshot({
+		lastSync: status.lastSync,
+		checkedAt: new Date().toISOString(),
+	});
+}
+
+/**
+ * Records a sync that just completed. The stored `lastSync` is our own clock
+ * rather than the server's, which is close enough to keep later reads quiet.
+ */
+export function recordSyncNow(): void {
+	const now = new Date().toISOString();
+	saveSnapshot({ lastSync: now, checkedAt: now });
+}
+
+function isFresh(
+	snapshot: FreshnessSnapshot | null,
+	thresholdMs: number,
+	now: number,
+): boolean {
+	const ageMs = snapshotAgeMs(snapshot, now);
+	return ageMs !== null && ageMs < thresholdMs;
+}
+
+function snapshotAgeMs(
+	snapshot: FreshnessSnapshot | null,
+	now: number,
+): number | null {
+	if (!snapshot?.lastSync) return null;
+	const syncedAt = Date.parse(snapshot.lastSync);
+	if (!Number.isFinite(syncedAt)) return null;
+	return Math.max(0, now - syncedAt);
+}
+
+function loadSnapshot(): FreshnessSnapshot | null {
+	const read = readPrivateFile(STATE_FILE);
+	if (read.kind !== "ok") return null;
+
+	try {
+		const parsed = JSON.parse(read.text) as Partial<FreshnessSnapshot>;
+		if (typeof parsed.checkedAt !== "string") return null;
+		return {
+			lastSync: typeof parsed.lastSync === "string" ? parsed.lastSync : null,
+			checkedAt: parsed.checkedAt,
+		};
+	} catch {
+		return null;
+	}
+}
+
+function saveSnapshot(snapshot: FreshnessSnapshot): FreshnessSnapshot {
+	try {
+		writePrivateFile(STATE_FILE, JSON.stringify(snapshot) + "\n");
+	} catch {
+		// A read-only config dir must not break vault access.
+	}
+	return snapshot;
+}

package/src/bw/items.ts

@@ -0,0 +1,25 @@
+import { BW_TYPE_LABELS } from "./types.ts";
+
+/**
+ * The only shape of a vault item bwx prints when the caller did not ask for a
+ * specific secret. Enough to identify an item and follow up with a narrow `get`,
+ * with no room for passwords, notes, custom fields, or URIs to leak into logs.
+ */
+export interface ItemSummary {
+	id: string;
+	type: string;
+	name: string;
+	username: string | null;
+}
+
+export function summarizeItem(item: Record<string, unknown>): ItemSummary {
+	const login = item.login as Record<string, unknown> | null | undefined;
+	const username = login?.username;
+
+	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,
+	};
+}

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