bwx 0.4.1 → 0.6.0

package/README.md

@@ -54,28 +54,114 @@ bwx doctor
 
 | Command | Description |
 |---------|-------------|
-| `bwx status` | Show vault state |
+| `bwx status` | Show vault state and whether reads work right now |
 | `bwx unlock` | Unlock vault & cache session |
 | `bwx lock` | Lock vault & clear session |
 | `bwx sync` | Sync vault from server |
 | `bwx doctor` | Check setup (bw CLI, email, password, config) |
 
+`status` reports a `session` alongside the vault state, because `bw` answers for the
+vault and not for bwx: a `locked` vault with a `valid` session reads fine and needs no
+unlock. `valid` means reads work now, `stale` means the cached session was rejected, and
+`none` means the next read unlocks.
+
 ### Read
 
 | Command | Description |
 |---------|-------------|
 | `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`) |
-| `bwx field <item> <name>` | Get custom field by name |
+| `bwx get totp <item>` | TOTP code (`--fresh [n]`, `--seed`) |
+| `bwx field <name> <item>` | Get custom field by name (same argument order as `get`) |
 | `bwx search <query>` | Search items (`--type`, `--folder`, `--limit`, `--full-items`) |
-| `bwx list [type]` | List items (`--folder`, `--limit`, `--full-items`) |
+| `bwx list [type]` | List items (`--type`, `--folder`, `--limit`, `--full-items`) |
+| `bwx folders` | List folder names and IDs |
+| `bwx trash` | List items in the trash |
 | `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.
+`search` and `list` print the same reduced projection — id, type, name, username,
+hasTotp — 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.
+
+`hasTotp` reports that an item has a TOTP secret without carrying it, so finding your 2FA
+items does not mean dumping the vault:
+
+```bash
+bwx list --json --limit 0 | jq -r '.data[] | select(.hasTotp) | .name'
+```
+
+A lookup that finds nothing suggests what you probably meant, and one that matches
+several items lists them, so neither ends in a guessing round:
+
+```
+$ bwx get password "GitHub PAT vforsh old"
+error: No item matching "GitHub PAT vforsh old". Did you mean:
+
+  934c1f57-…  note  GitHub PAT (vforsh)
+  3683fb9a-…  note  GitHub PAT (yaforsh) [codex-monitor-pr]
+```
+
+### TOTP
+
+Codes are computed locally from the stored secret. A TOTP therefore costs no extra `bw`
+spawn and batches with the other fields of the same item, and bwx can report how long the
+code has left.
+
+```bash
+bwx get totp "AWS"              # code on stdout, "Valid for 17s" on stderr
+bwx get totp "AWS" --json       # { "data": "123456", "meta": { "secondsRemaining": 17, "period": 30 } }
+bwx get totp "AWS" --fresh      # wait for the next window if under 5s remain
+bwx get totp "AWS" --fresh 15   # ...or under 15s
+bwx get totp "AWS" --seed       # the stored secret, for moving it to another authenticator
+```
+
+The remainder matters more than it looks: a vault read plus the time to actually use the
+code often leaves single-digit seconds, and a code that expires in transit fails the login
+without saying why. `--fresh` sleeps at most one period and hands back a full window.
+
+Bare base32 and `otpauth://` URIs are both understood, including non-default `period`,
+`digits`, and `algorithm` (SHA1/SHA256/SHA512). Secrets bwx will not compute exactly —
+`steam://`, unknown algorithms, anything that fails to decode — fall back to `bw get totp`
+rather than being guessed at, since a wrong code is indistinguishable from a right one
+until the login fails.
+
+Storing a secret:
+
+```bash
+BWX_SEED="JBSWY3DPEHPK3PXP" bwx create --type login --name "AWS" --username me --totp-env BWX_SEED
+bwx edit "AWS" --totp "otpauth://totp/AWS:me?secret=JBSWY3DPEHPK3PXP&issuer=AWS"
+bwx edit "AWS" --rm-totp
+```
+
+Spaces, hyphens, and `=` padding are stripped and case is normalized; an `otpauth://` URI
+is stored verbatim so its parameters survive. Malformed secrets are rejected before the
+write, because a bad seed is otherwise discovered at the login it was supposed to unlock.
+
+### Listings are capped
+
+Listings stop at 50 items by default — an uncapped `bwx list` returns the whole vault,
+and with `--full-items` that is every secret in one call. `--limit 0` opts out. Truncation
+is never silent: it warns on stderr (surviving `--json`) and adds `meta` to the JSON
+envelope.
+
+```bash
+bwx list --limit 0            # everything
+bwx list --json               # { "data": [...], "meta": { "total": 491, "shown": 50, "truncated": true } }
+```
+
+### Folders
+
+`--folder` takes a name or an ID on `list`, `search`, `create`, and `edit`; `none` means
+the unfiled bucket. Names are resolved against the vault, so `bwx folders` is only needed
+to see what exists.
+
+```bash
+bwx folders
+bwx list --folder "API Keys"
+bwx edit "Acme" --folder none     # unfile
+```
 
 ### Secrets into a child process
 
@@ -111,9 +197,37 @@ The check is cached in `~/.config/bwx/state.json`, so a fresh vault costs no ext
 
 | Command | Description |
 |---------|-------------|
-| `bwx create` | Create item (`--type`, `--name`, `--username`, `--password-stdin`, `--field-file k=path`) |
-| `bwx edit <item>` | Edit item (`--name`, `--password-env`, `--add-field-file k=path`, `--rm-field name`) |
+| `bwx create` | Create item (`--type`, `--name`, `--username`, `--password-stdin`, `--totp-env`, `--field-file k=path`) |
+| `bwx edit <item>` | Edit item (`--name`, `--password-env`, `--totp`, `--rm-totp`, `--add-field-file k=path`, `--rm-field name`) |
 | `bwx delete <item>` | Delete item (`--permanent`, `--force`) |
+| `bwx restore <item>` | Restore an item from the trash |
+| `bwx generate` | Generate a password or passphrase (local, no vault access) |
+
+Login-only flags (`--username`, any `--password-*` or `--totp-*`, `--uri`) require a login
+item. A secure note has nowhere to put them, so passing them to one is an error rather
+than an exit 0 over a credential that was silently dropped.
+
+`bwx delete` requires `--force` whenever it is not talking to a terminal. The confirmation
+prompt cannot render for a script or an agent, so without it `--force` would be decorative
+and every non-interactive delete unguarded. Deletes go to the trash unless `--permanent`,
+and `bwx trash` / `bwx restore` are the way back.
+
+### Generated passwords
+
+`--password-generate` on `create` and `edit` sends a new secret straight to the vault. It
+is never printed, never echoed back in `--json`, and never reaches a terminal, a
+transcript, or a log — which is what makes it safe to use from an agent.
+
+```bash
+bwx create --type login --name "Deploy" --username svc --password-generate
+bwx edit "Deploy" --password-generate --generate-length 32
+bwx generate --length 32                  # print one instead
+bwx generate --passphrase --words 5
+```
+
+`bwx generate` runs locally and needs no unlocked vault. Flags: `--length <n>`,
+`--no-uppercase`, `--no-lowercase`, `--no-numbers`, `-s/--special`, `--ambiguous`,
+`--passphrase`, `--words <n>`, `--separator <char>`, `--capitalize`, `--include-number`.
 
 ### Config
 
@@ -147,6 +261,7 @@ bwx create --name "Acme" --field-file '!API Key=./token.txt' --field-env account
 Supported source flags:
 
 - Passwords: `--password-stdin`, `--password-file <path>`, `--password-env <name>`
+- TOTP secrets: `--totp-stdin`, `--totp-file <path>`, `--totp-env <name>`
 - Notes: `--notes-file <path>`
 - Create fields: `--field-file k=path`, `--field-env k=ENV`
 - Edit fields: `--add-field-file k=path`, `--add-field-env k=ENV`
@@ -156,7 +271,7 @@ Supported source flags:
 
 | Flag | Effect |
 |------|--------|
-| `--json` | JSON output: `{ "data": ... }` / `{ "error": ... }` |
+| `--json` | JSON output: `{ "data": ... }` / `{ "error": ... }`, plus `meta` where a response describes itself |
 | `--plain` | Tab-separated, one item per line |
 | `-q, --quiet` | Suppress logs and warnings |
 | `-v, --verbose` | Include stack traces |
@@ -191,6 +306,17 @@ Field syntax for `--field`, `--field-file`, `--field-env`, and edit variants:
 | 8 | Timeout |
 | 9 | User cancelled |
 
+## Upgrading to 0.5.0
+
+Breaking changes, all of them cases where the old behavior failed quietly:
+
+- `bwx field` takes `<name> <item>`, matching `bwx get`. It was `<item> <name>`.
+- `bwx delete` needs `--force` when not interactive; it used to delete unprompted.
+- `bwx list` and `bwx search` stop at 50 items unless given `--limit`. Pass `--limit 0`
+  for the old behavior.
+- `--limit` rejects non-numeric values instead of ignoring them (and returning everything).
+- Login-only flags on a secure note are an error instead of a silent drop.
+
 ## Stack
 
 Bun, TypeScript, Commander, Zod, picocolors.

package/package.json

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

package/skill/bwx/SKILL.md

@@ -11,13 +11,14 @@ Extended Bitwarden CLI. Wraps `bw` with auto-unlock, session caching, and struct
 
 ```bash
 bwx get password "GitHub"               # retrieve a password (auto-unlocks)
-bwx get totp "AWS (user@example.com)"   # TOTP code
+bwx get totp "AWS (user@example.com)"   # TOTP code (+ seconds left, on stderr)
+bwx get totp "AWS" --fresh              # wait out a nearly-expired code first
 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 field "API Key" "Acme"              # custom-field-only lookup, same arg order
 
 bwx search github                       # fuzzy search, human table
 bwx search github --json                # id/type/name/username only — no secrets
@@ -26,6 +27,9 @@ 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
 
+# generate straight into the vault — the value never enters your context
+bwx create --type login --name "Deploy" --username svc --password-generate
+
 bwx attach list "Apple Developer"       # list item attachments
 bwx attach get "Apple Developer" AuthKey.p8
 bwx attach get "Apple Developer" AuthKey.p8 --output ./secrets/
@@ -43,17 +47,56 @@ echo "secret" | bwx create --name "Piped Note"
 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>`
+A miss suggests near matches; an ambiguous name lists candidates with IDs. Read the
+suggestions instead of retrying variations — the answer is usually in them.
+
+### `bwx get totp <item>`
+
+Codes are computed locally from the stored secret, so a TOTP costs no extra `bw` spawn and
+batches with other fields from the same item.
+
+```bash
+bwx get totp "AWS"                  # code on stdout, "Valid for 17s" on stderr
+bwx get totp "AWS" --json           # { "data": "123456", "meta": { "secondsRemaining", "period" } }
+bwx get totp "AWS" --fresh          # wait for the next window if under 5s remain
+bwx get totp "AWS" --fresh 15       # ...or under 15s
+bwx get totp "AWS" --seed           # the stored secret, for migrating to another app
+```
+
+**Check `secondsRemaining` before using a code.** A `bw` read plus the time to hand the code
+over routinely leaves under 5 seconds, and a code that expires in transit fails the login
+with no useful error. `--fresh` sleeps at most one period and returns a full-window code.
 
-Alias for retrieving custom fields with item-first argument order.
+Accepts bare base32 and `otpauth://` URIs, honoring their `period`, `digits`, and
+`algorithm` (SHA1/SHA256/SHA512). `steam://` secrets and anything else bwx cannot compute
+exactly are delegated to `bw get totp` instead of guessed at.
+
+### `bwx field <name> <item>`
+
+Custom fields only, so an item whose custom field is named `password` is still reachable.
+Takes its arguments in the same order as `get` (this changed in 0.5.0).
 
 ### `bwx search <query>` / `bwx list [type]`
 
-Flags: `--type login|note|card|identity` (`search`), `--folder <id>`, `--limit <n>`, `--full-items`
+Flags: `--type login|note|card|identity`, `--folder <name|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.
+`name`, `username`, `hasTotp` — 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.
+
+`hasTotp` says whether an item has a TOTP secret, never what it is. Use it to find 2FA items
+(`bwx list --json --limit 0 | jq '.data[]|select(.hasTotp)'`) instead of reaching for
+`--full-items`, which would dump the whole vault in plaintext to answer a boolean.
+
+**Listings stop at 50 items** unless you pass `--limit` (`--limit 0` for all). Truncation is
+reported on stderr and in `meta` on the JSON envelope — check it before concluding a listing
+was complete. `--limit` rejects non-numeric values rather than ignoring them.
+
+### `bwx folders`
+
+Lists folder names and IDs. `--folder` accepts either on `list`, `search`, `create`, and
+`edit`; `none` selects unfiled items.
 
 ### `bwx run --env NAME=<field>:<item> -- <command>`
 
@@ -70,6 +113,8 @@ bwx run --env TOKEN='API Key:Acme' --env USER=username:Acme -- ./deploy.sh
 - 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.
+- Several variables from one item cost a single vault read, so group them here rather
+  than issuing separate `bwx get` calls.
 
 ### `bwx attach list <item>`
 
@@ -81,7 +126,10 @@ Downloads an attachment by ID or filename. Defaults to saving as the attachment
 
 ### `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`
+Flags: `--type login|note`, `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--password-generate`, `--generate-length <n>`, `--totp`, `--totp-stdin`, `--totp-file`, `--totp-env`, `--uri` (repeatable), `--field k=v` (repeatable), `--field-file k=path`, `--field-env k=ENV`, `--folder <name|id>`, `--favorite`, `--from-json`
+
+`--username`, any `--password-*` or `--totp-*`, and `--uri` require `--type login`; a note
+cannot hold them and passing them to one is now an error rather than a silent drop.
 
 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.
 
@@ -93,26 +141,68 @@ 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`
+Flags: `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--password-generate`, `--generate-length <n>`, `--totp`, `--totp-stdin`, `--totp-file`, `--totp-env`, `--rm-totp`, `--uri` (replaces all), `--add-field k=v`, `--add-field-file k=path`, `--add-field-env k=ENV`, `--rm-field name`, `--folder <name|id>` (`none` unfiles), `--favorite/--no-favorite`, `--from-json`
+
+### Storing a TOTP secret
+
+```bash
+BWX_SEED="JBSWY3DPEHPK3PXP" bwx create --type login --name "AWS" --username me --totp-env BWX_SEED
+bwx edit "AWS" --totp "otpauth://totp/AWS:me?secret=JBSWY3DPEHPK3PXP&issuer=AWS"
+bwx edit "AWS" --rm-totp
+```
+
+Takes a bare base32 secret (spaces, hyphens, and `=` padding are stripped; case is
+normalized) or a full `otpauth://` URI, which is stored verbatim so its `period`/`digits`/
+`algorithm` survive. Malformed secrets are rejected **before** the write — a bad seed
+otherwise sits in the vault until it fails the login it was meant to unlock, which is the
+one moment it cannot be fixed.
+
+Prefer `--totp-env` or `--totp-stdin` over `--totp`: a seed on the command line lands in
+shell history and `ps` output.
 
 ### `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
+bwx delete "Test Note" --force      # --force is REQUIRED when not a TTY
+bwx delete "Test Note" --permanent --force  # skip the trash
+bwx trash                           # what is recoverable
+bwx restore "Test Note"             # undo a non-permanent delete
+```
+
+The prompt only exists for a human at a terminal, so an agent must pass `--force`
+deliberately. Deletes are recoverable through `bwx restore` unless `--permanent`.
+
+### `bwx generate`
+
+```bash
+bwx generate --length 32
+bwx generate --passphrase --words 5 --separator -
 ```
 
+Local, no vault access, no unlock. Flags: `--length <n>`, `--no-uppercase`,
+`--no-lowercase`, `--no-numbers`, `-s/--special`, `--ambiguous`, `--passphrase`,
+`--words <n>`, `--separator <char>`, `--capitalize`, `--include-number`.
+
+Prefer `--password-generate` on `create`/`edit` over generating and passing the value:
+it goes to the vault without ever entering your context, and `--json` returns
+`***GENERATED***` in place of the password.
+
 ### Other
 
 | Command | Description |
 |---------|-------------|
-| `bwx status` | Vault state (no auto-unlock) |
+| `bwx status` | Vault state + session usability (no auto-unlock) |
 | `bwx sync` | Force vault sync |
 | `bwx unlock` / `bwx lock` | Manual session control |
+| `bwx folders` | Folder names and IDs |
+| `bwx trash` / `bwx restore <item>` | Inspect and undo deletes |
 | `bwx config list` / `bwx cfg ls` | Show config path + redacted content |
 | `bwx config master-password` | Set/update master password in Keychain |
 
+`bwx status` reports `session: valid | stale | none` separately from the vault state.
+**A `locked` vault with a `valid` session reads fine — do not run `bwx unlock` on it.**
+Only `stale`/`none` mean the next read pays for an unlock.
+
 ## Global flags
 
 | Flag | Effect |
@@ -137,9 +227,12 @@ even under `--json`; `-q` silences them.
 
 - 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.
+- Prefer `--password-generate` over generating a secret yourself and passing it in.
 - 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`.
+- On writes, prefer `--password-stdin`, `--password-env`, `--totp-stdin`, `--totp-env`, `--field-file`, `--field-env`.
+- Check `secondsRemaining` on a TOTP, or pass `--fresh`, before handing the code anywhere.
+- Use `hasTotp` on a listing to find 2FA items; never `--full-items` for that.
 - Never echo, log, checksum, or commit retrieved values; `unset` temporary variables.
 
 ## Auth

package/src/bw/encoding.ts

@@ -40,6 +40,7 @@ export interface NewItemOptions {
 	notes?: string | null;
 	username?: string | null;
 	password?: string | null;
+	totp?: string | null;
 	uris?: string[];
 	fields?: ParsedField[];
 	folderId?: string | null;
@@ -65,7 +66,7 @@ export function buildNewItem(options: NewItemOptions): Record<string, unknown> {
 		item.login = {
 			username: options.username ?? null,
 			password: options.password ?? null,
-			totp: null,
+			totp: options.totp ?? null,
 			uris: options.uris?.length
 				? options.uris.map((uri) => ({ match: null, uri }))
 				: null,
@@ -95,10 +96,13 @@ export interface PatchOptions {
 	notes?: string;
 	username?: string;
 	password?: string;
+	/** `null` clears the stored secret; `undefined` leaves it alone. */
+	totp?: string | null;
 	uris?: string[];
 	addFields?: ParsedField[];
 	rmFields?: string[];
-	folderId?: string;
+	/** `null` unfiles the item; `undefined` leaves its folder alone. */
+	folderId?: string | null;
 	favorite?: boolean;
 }
 
@@ -114,10 +118,18 @@ export function patchItem(
 	if (patch.favorite !== undefined) result.favorite = patch.favorite;
 
 	// Login fields
-	if (patch.username !== undefined || patch.password !== undefined || patch.uris !== undefined) {
-		const login = (result.login as Record<string, unknown>) ?? {};
+	if (
+		patch.username !== undefined ||
+		patch.password !== undefined ||
+		patch.totp !== undefined ||
+		patch.uris !== undefined
+	) {
+		// Copied, not aliased: `{ ...item }` above is shallow, so assigning into
+		// the original `login` would edit the caller's item as a side effect.
+		const login = { ...((result.login as Record<string, unknown>) ?? {}) };
 		if (patch.username !== undefined) login.username = patch.username;
 		if (patch.password !== undefined) login.password = patch.password;
+		if (patch.totp !== undefined) login.totp = patch.totp;
 		if (patch.uris !== undefined) {
 			login.uris = patch.uris.map((uri) => ({ match: null, uri }));
 		}