bwx 0.3.0 → 0.4.1

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.1",
   "type": "module",
   "keywords": [
     "bitwarden",
@@ -12,7 +12,8 @@
   ],
   "files": [
     "bin",
-    "src"
+    "src",
+    "skill"
   ],
   "bin": {
     "bwx": "bin/bwx"

package/skill/bwx/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: bwx
+description: Bitwarden Extended CLI — retrieve, create, edit, delete vault items with auto-unlock. Use when the agent needs passwords, API keys, TOTP codes, custom fields, or vault management. Triggers on mentions of Bitwarden, bw, bwx, vault, password, secrets, TOTP, save key/token.
+---
+
+# bwx
+
+Extended Bitwarden CLI. Wraps `bw` with auto-unlock, session caching, and structured output.
+
+## Quick start
+
+```bash
+bwx get password "GitHub"               # retrieve a password (auto-unlocks)
+bwx get totp "AWS (user@example.com)"   # TOTP code
+bwx get username "GitHub"               # username
+bwx get notes "Deploy key"              # secure note content
+bwx get uri "GitHub"                    # first URI
+bwx get item "GitHub"                   # full item JSON
+bwx get "API Key" "Acme"                # custom field by name
+bwx field "Acme" "API Key"              # custom field alias
+
+bwx search github                       # fuzzy search, human table
+bwx search github --json                # id/type/name/username only — no secrets
+bwx search github --type login --limit 5
+
+# hand a secret to a child process instead of printing it
+bwx run --env KEENETIC_PASS=password:'http://my.keenetic.net' -- expect ./recovery.exp
+
+bwx attach list "Apple Developer"       # list item attachments
+bwx attach get "Apple Developer" AuthKey.p8
+bwx attach get "Apple Developer" AuthKey.p8 --output ./secrets/
+
+bwx create --name "API Key" --notes "sk_live_abc123" --field account=acme
+printf '%s' "$TOKEN" | bwx create --type login --name "GitHub" --username user --password-stdin --uri https://github.com
+bwx create --name "Acme" --field-file '!API Key=./token.txt' --field-env account=ACME_ACCOUNT
+echo "secret" | bwx create --name "Piped Note"
+```
+
+## Commands
+
+### `bwx get <field> <item>`
+
+Built-in fields: `password | username | totp | notes | uri | item`.
+Anything else is looked up as a custom field. Lists available fields on miss.
+
+### `bwx field <item> <name>`
+
+Alias for retrieving custom fields with item-first argument order.
+
+### `bwx search <query>` / `bwx list [type]`
+
+Flags: `--type login|note|card|identity` (`search`), `--folder <id>`, `--limit <n>`, `--full-items`
+
+Human, `--plain`, and `--json` output all carry the same reduced projection — `id`, `type`,
+`name`, `username` — so listings never leak passwords, notes, or custom fields. `--full-items`
+opts into complete item objects and **does** include secrets; avoid it in logged sessions.
+
+### `bwx run --env NAME=<field>:<item> -- <command>`
+
+Resolves secrets and injects them into the child's environment only — not stdout, not argv.
+This is the preferred way to give a subprocess a credential.
+
+```bash
+bwx run --env DB_PASS=password:'Prod DB' -- ./migrate.sh
+bwx run --env TOKEN='API Key:Acme' --env USER=username:Acme -- ./deploy.sh
+```
+
+- `--env` is repeatable; the field resolves as in `bwx get` (built-in, else custom field).
+- Only the first `:` splits field from item, so `password:http://my.router` works.
+- Put `--` before the command when it takes its own flags.
+- Child stdio is inherited; bwx exits with the child's status (`128 + signal` if killed).
+- `-v` logs injected variable names only, never values.
+
+### `bwx attach list <item>`
+
+Lists attachments for an item. Aliases: `bwx attachment`, `bwx attachments`; `list` has `ls`.
+
+### `bwx attach get <item> <attachment>`
+
+Downloads an attachment by ID or filename. Defaults to saving as the attachment filename in the current directory. Use `--output <path>` to choose a file or directory.
+
+### `bwx create [options]`
+
+Flags: `--type login|note`, `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--uri` (repeatable), `--field k=v` (repeatable), `--field-file k=path`, `--field-env k=ENV`, `--folder`, `--favorite`, `--from-json`
+
+Field syntax: `k=v` (text), `!k=v` (hidden), `bool:k=v` (boolean). The same key syntax works for `--field-file` and `--field-env`, where the value is a path or environment variable name. Stdin is read as `--notes` when piped; prefer `--password-stdin` for login passwords.
+
+### `bwx edit <item> [options]`
+
+Fetch → patch → push.
+```bash
+bwx edit "API Key" --add-field region=us-east-1
+printf '%s' "$TOKEN" | bwx edit "GitHub" --password-stdin --uri https://github.com
+bwx edit "Note" --rm-field old-key
+```
+Flags: `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--uri` (replaces all), `--add-field k=v`, `--add-field-file k=path`, `--add-field-env k=ENV`, `--rm-field name`, `--folder`, `--favorite/--no-favorite`, `--from-json`
+
+### `bwx delete <item>`
+
+```bash
+bwx delete "Test Note"              # prompts in TTY
+bwx delete "Test Note" --force      # skip prompt
+bwx delete "Test Note" --permanent  # no trash
+```
+
+### Other
+
+| Command | Description |
+|---------|-------------|
+| `bwx status` | Vault state (no auto-unlock) |
+| `bwx sync` | Force vault sync |
+| `bwx unlock` / `bwx lock` | Manual session control |
+| `bwx config list` / `bwx cfg ls` | Show config path + redacted content |
+| `bwx config master-password` | Set/update master password in Keychain |
+
+## Global flags
+
+| Flag | Effect |
+|------|--------|
+| `--json` | `{ "data": ... }` on success, `{ "error": { "message", "exitCode" } }` on failure |
+| `--plain` | Stable parseable lines on stdout |
+| `-q` | Suppress logs and warnings |
+| `-v` | Verbose (stack traces on error) |
+| `--timeout <duration>` | Deadline per `bw` call (default `1m`, `0` disables) → exit 8 |
+| `--sync-if-older-than <duration>` | Sync first when the vault last synced longer ago |
+
+Durations: `250ms`, `30s`, `15m`, `2h`, `1d`; a bare number is seconds.
+
+## Vault freshness
+
+Reads come from the local vault copy. Reads warn on stderr when the last sync is over 24h
+old — a rotated secret can otherwise look valid or missing. Pass
+`--sync-if-older-than 15m` to sync first instead, or run `bwx sync`. Warnings reach stderr
+even under `--json`; `-q` silences them.
+
+## Safety rules
+
+- Never use `--full-items` (or `get item` for discovery) in logged sessions.
+- Prefer `bwx run --env ...` over `export VAR="$(bwx get ...)"`; secrets never touch stdout or argv.
+- Request the narrowest field, resolving an exact item ID first.
+- Use `-q` for command substitution so unlock logs cannot contaminate merged output.
+- On writes, prefer `--password-stdin`, `--password-env`, `--field-file`, `--field-env`.
+- Never echo, log, checksum, or commit retrieved values; `unset` temporary variables.
+
+## Auth
+
+- Master password: macOS Keychain (account `bitwarden`, service `bitwarden-master`)
+- Session cached to `~/.config/bwx/session` (mode 600), given to `bw` via `BW_SESSION`
+- Freshness snapshot cached to `~/.config/bwx/state.json`

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