bwx 0.8.0 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladislav Forsh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -69,15 +69,15 @@ unlock. `valid` means reads work now, `stale` means the cached session was rejec
 
 | Command | Description |
 |---------|-------------|
-| `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`), `--raw` |
+| `bwx get <field> <item>` / `bwx get <ref>` | Get a field or discovered reference, `--raw` |
 | `bwx get totp <item>` | TOTP code (`--fresh [n]`, `--seed`) |
 | `bwx get <card field> <item>` | Card field (`number`, `cvv`, `cardholder`, `brand`, `expiry`, …) |
 | `bwx field <name> <item>` | Get custom field by name (same argument order as `get`), `--raw` |
-| `bwx search <query>` | Search items (`--type`, `--folder`, `--limit`, `--full-items`) |
+| `bwx search <query>` / `bwx find <query>` | Search items (`--fields`, `--type`, `--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 run --env NAME=<field>:<item> -- <cmd>` / `--env NAME=<ref>` | 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 |
 
@@ -104,6 +104,63 @@ error: No item matching "GitHub PAT vforsh old". Did you mean:
   3683fb9a-…  note  GitHub PAT (yaforsh) [codex-monitor-pr]
 ```
 
+### Discover fields without values
+
+`search` (alias `find`) accepts `--fields` to return only item `id`, `type`, `name`,
+and `fields`. Each field has `kind` (`builtin` or `custom`), `name`, `type`, and a
+consumable `ref`. Even usernames and URIs are described without their values in this
+mode. `--fields` cannot be combined with `--full-items`.
+
+```bash
+bwx find "Deploy token" --fields --json
+# { "data": [{ "id": "11111111-2222-3333-4444-555555555555", "type": "note",
+#   "name": "Deploy token", "fields": [{ "kind": "builtin", "name": "notes",
+#   "type": "text", "ref": "bwx://11111111-2222-3333-4444-555555555555/builtin/notes" }] }],
+#   "meta": { "total": 1, "shown": 1, "truncated": false } }
+
+# Copy the ref from discovery. Only the child receives the token.
+bwx run --env 'TOKEN=bwx://11111111-2222-3333-4444-555555555555/builtin/notes' -- ./deploy.sh
+
+# Or pipe the referenced bytes directly to a consumer; get itself prints the value.
+bwx get 'bwx://11111111-2222-3333-4444-555555555555/builtin/notes' --raw | ./consume-token
+```
+
+Supported capabilities:
+
+- Nonempty `notes` on every item type, including Secure Notes containing API tokens.
+- Login `username`, `password`, first `uri`, and `totp` when present. A TOTP reference
+  resolves to a code using the existing local computation or `bw` fallback; it does not
+  carry the seed. `get <totp-ref>` also supports `--fresh` and `--seed`.
+- Card `number`, `cvv`, `cardholder`, `brand`, `expiry`, `expMonth`, `expYear` when
+  available, with the same normalization as `get`. `expiry` needs both month and year.
+- Custom text, hidden, and boolean fields on every item type, including empty values
+  (`null` is read as an empty string). Linked and unknown custom types are omitted.
+  Identity-specific and full-item fields are not advertised.
+
+Field `type` is `text`, `hidden`, `boolean`, or `totp`; these are capability labels,
+not a claim that text fields are safe to print. Notes often hold secrets.
+
+References use `bwx://<item-id>/builtin/<canonical-field>` or
+`bwx://<item-id>/custom/<zero-based-index>/<percent-encoded-name>`. Custom names may
+contain spaces, colons, slashes, percent signs, Unicode, or be empty. A custom field
+named `password` has its own reference and never resolves to the login password.
+Copy references verbatim and quote them in shell commands.
+
+Item renaming does not change references: reads use the exact ID and verify it in the
+response. Custom references address a position and check the name there, which also
+distinguishes duplicate names. Rediscover after renaming/reordering/removing custom
+fields; a changed name at that position fails, while swapping identical names can
+retarget the reference because Bitwarden supplies no custom-field IDs. References
+resolve current values from the local vault; they are not snapshots or access grants.
+
+Filters, the default 50-item cap, `--limit 0`, and truncation warnings/meta work as usual.
+Human output groups fields under each item; `--plain` has four tab-separated columns:
+`id`, `type`, JSON-quoted `name`, and a compact JSON `fields` array, one item per line.
+JSON escaping preserves tabs/newlines in names without breaking rows. Discovery uses
+the existing list response without extra per-item reads. Vault errors and malformed
+responses are reported without raw diagnostics or value-bearing parse excerpts,
+including under `-v`.
+
 ### Piping a secret
 
 `get` and `field` end their output with a newline, which reads fine in a terminal and
@@ -202,6 +259,31 @@ process](#secrets-into-a-child-process):
 bwx run --env NUM=number:Visa --env CVV=cvv:Visa --env EXP=expiry:Visa -- ./pay.sh
 ```
 
+Storing a card:
+
+```bash
+bwx create --type card --name "Visa Work" --cardholder "Vladislav Forsh" \
+  --expiry 08/29 --number-stdin --cvv-env CARD_CVV < number.txt
+bwx edit "Visa Work" --expiry 09/31 --cvv-stdin   # changes only these fields
+bwx edit "Visa Work" --rm-cvv --rm-brand
+```
+
+The number and CVV take the same sources as a password (`--number`, `--number-stdin`,
+`--number-file`, `--number-env`; `--cvv*` likewise). Values are checked before the write
+and errors never echo them:
+
+- Number: spaces and dashes are stripped, then it must be digits and pass a Luhn check
+  (`--no-validate` skips Luhn for test or private-label numbers).
+- CVV: 3–4 digits.
+- Expiry: `--expiry MM/YY|MM/YYYY`, or `--exp-month 1-12` / `--exp-year YYYY`; a two-digit
+  year becomes `20YY`.
+- Brand: any casing of `Visa`, `Mastercard`, `Amex`, `Discover`, `Diners Club`, `JCB`,
+  `Maestro`, `UnionPay`, `RuPay`, `Mir`, `Other`. Omitted, it is inferred from the number
+  when the prefix is unambiguous — on `edit`, only onto a card that has no brand yet.
+
+`edit` clears with `--rm-number`, `--rm-cvv`, `--rm-cardholder`, `--rm-brand`,
+`--rm-expiry`. Card flags on a non-card item, and login flags on a card, are usage errors.
+
 ### Listings are capped
 
 Listings stop at 50 items by default — an uncapped `bwx list` returns the whole vault,
@@ -238,11 +320,15 @@ bwx run --env DB_PASS=password:'Prod DB' --env TOKEN='API Key:Acme' -- ./deploy.
 
 - `--env NAME=<field>:<item>` is repeatable; the field resolves exactly as in `bwx get`
   (built-ins first, otherwise a custom field name).
+- `--env NAME=<ref>` accepts references from `search --fields`, including explicit
+  custom-field references. Several references to the same item share one vault read.
 - 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.
 
+The child inherits stdout/stderr, so choose a consumer that does not print its secrets.
+
 ### Vault freshness
 
 `bw` answers reads from the local vault copy, so a vault that has not synced in a while
@@ -260,15 +346,16 @@ 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`, `--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 create` | Create item (`--type login\|note\|card`, `--name`, `--username`, `--password-stdin`, `--totp-env`, `--number-stdin`, `--cvv-env`, `--expiry`, `--field-file k=path`) |
+| `bwx edit <item>` | Edit item (`--name`, `--password-env`, `--totp`, `--rm-totp`, `--expiry`, `--cvv-stdin`, `--rm-cvv`, `--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.
+item, and card flags (`--cardholder`, `--brand`, `--expiry`, `--exp-*`, `--number*`, `--cvv*`,
+`--rm-*` for them) a card item. Any other type has nowhere to put them, so passing them is
+an error rather than an exit 0 over a value 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
@@ -325,6 +412,8 @@ Supported source flags:
 
 - Passwords: `--password-stdin`, `--password-file <path>`, `--password-env <name>`
 - TOTP secrets: `--totp-stdin`, `--totp-file <path>`, `--totp-env <name>`
+- Card numbers: `--number-stdin`, `--number-file <path>`, `--number-env <name>`
+- CVVs: `--cvv-stdin`, `--cvv-file <path>`, `--cvv-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`
@@ -383,3 +472,7 @@ Breaking changes, all of them cases where the old behavior failed quietly:
 ## Stack
 
 Bun, TypeScript, Commander, Zod, picocolors.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,15 +1,34 @@
 {
   "name": "bwx",
-  "version": "0.8.0",
-  "type": "module",
+  "version": "0.10.0",
+  "description": "Extended Bitwarden CLI for scripts and agents — auto-unlock via macOS Keychain, session caching, local TOTP, structured output",
   "keywords": [
     "bitwarden",
+    "bitwarden-cli",
     "cli",
     "vault",
     "secrets",
+    "secrets-management",
+    "totp",
+    "keychain",
+    "macos",
     "ai-agents",
     "bun"
   ],
+  "license": "MIT",
+  "author": "Vladislav Forsh <vforsh@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vforsh/bwx.git"
+  },
+  "homepage": "https://github.com/vforsh/bwx#readme",
+  "bugs": {
+    "url": "https://github.com/vforsh/bwx/issues"
+  },
+  "type": "module",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
   "files": [
     "bin",
     "src",
@@ -24,10 +43,8 @@
     "cmd": "bun run bin/bwx"
   },
   "devDependencies": {
-    "@types/bun": "latest"
-  },
-  "peerDependencies": {
-    "typescript": "^5"
+    "@types/bun": "latest",
+    "typescript": "^7"
   },
   "dependencies": {
     "commander": "^14.0.3",

package/skill/bwx/SKILL.md

@@ -23,8 +23,9 @@ bwx field "API Key" "Acme"              # custom-field-only lookup, same arg ord
 bwx get password "GitHub" --raw         # no trailing newline, for piping into stdin
 
 bwx search github                       # fuzzy search, human table
-bwx search github --json                # id/type/name/username only — no secrets
+bwx search github --json                # id/type/name/username/hasTotp — no secret contents
 bwx search github --type login --limit 5
+bwx find "Deploy token" --fields --json # available fields and refs, never their values
 
 # hand a secret to a child process instead of printing it
 bwx run --env KEENETIC_PASS=password:'http://my.keenetic.net' -- expect ./recovery.exp
@@ -40,15 +41,19 @@ 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"
+bwx create --type card --name "Visa Work" --cardholder "Vladislav Forsh" --expiry 08/29 --number-env CARD_NUM --cvv-env CARD_CVV
 ```
 
 ## Commands
 
-### `bwx get <field> <item>`
+### `bwx get <field> <item>` / `bwx get <ref>`
 
 Built-in fields: `password | username | totp | notes | uri | item`.
 Card items additionally take `number | cvv | cardholder | brand | expiry | expMonth | expYear`.
 Anything else is looked up as a custom field. Lists available fields on miss.
+Discovered `bwx://` references also work as the sole argument, including with `--raw`.
+`get` prints the referenced value: pipe it straight to a consumer instead of capturing
+it in an agent's context. TOTP references support `--fresh` and `--seed` as usual.
 
 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.
@@ -119,6 +124,7 @@ card field.
 ### `bwx search <query>` / `bwx list [type]`
 
 Flags: `--type login|note|card|identity`, `--folder <name|id>`, `--limit <n>`, `--full-items`
+`search` has alias `find` and additionally accepts `--fields` for field discovery.
 
 Human, `--plain`, and `--json` output all carry the same reduced projection — `id`, `type`,
 `name`, `username`, `hasTotp` — so listings never leak passwords, notes, or custom fields.
@@ -133,12 +139,56 @@ logged sessions.
 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.
 
+### Discovery → consume a reference
+
+Use `bwx search <query> --fields --json` to find an item and its available fields
+without reading `get item` or `--full-items`. Output is an explicit allowlist:
+item `id`, `type`, `name`, and `fields`; each field has only `kind`, `name`, `type`,
+and `ref`. Username/URI values are omitted too. `--fields` conflicts with `--full-items`.
+
+```bash
+bwx find "Deploy token" --fields --json
+# A Secure Note with content advertises:
+# { "kind": "builtin", "name": "notes", "type": "text",
+#   "ref": "bwx://11111111-2222-3333-4444-555555555555/builtin/notes" }
+
+# Copy that ref into run. The token goes only to the consumer's environment.
+bwx run --env 'TOKEN=bwx://11111111-2222-3333-4444-555555555555/builtin/notes' -- ./deploy.sh
+
+# If the consumer needs stdin, pipe directly; do not inspect get's stdout.
+bwx get 'bwx://11111111-2222-3333-4444-555555555555/builtin/notes' --raw | ./consume-token
+```
+
+- Nonempty `notes` appear on all item types. **API tokens commonly live in notes on
+  Secure Notes**; `text` describes the field type and does not mean its content is public.
+- Logins advertise nonempty `username`, `password`, first `uri`, and `totp`. TOTP
+  references yield codes through the existing computation/fallback, never the seed
+  unless explicitly consumed with `get <ref> --seed`.
+- Cards advertise available canonical card fields with existing normalization;
+  `expiry` requires both month and year. Identity-specific/full-item fields are omitted.
+- Custom text/hidden/boolean fields on any item type appear even with empty values;
+  null values resolve as empty strings. Linked/unknown types are omitted.
+- `kind` separates builtins and custom fields; custom `password`, `totp`, `item`, or
+  `cvv` references select the custom field. Types: `text`, `hidden`, `boolean`, `totp`.
+- Builtin syntax: `bwx://<item-id>/builtin/<canonical-field>`. Custom syntax:
+  `bwx://<item-id>/custom/<zero-based-index>/<percent-encoded-name>`. Copy verbatim and
+  shell-quote; empty names, duplicate names, Unicode and separators work.
+- Item renaming preserves refs. Custom refs check the name at the recorded position:
+  rediscover after changing field names/order. Swapping identical names can retarget
+  refs, since Bitwarden has no custom-field IDs. Refs read current local values and
+  require ordinary vault access; they are not snapshots or access grants.
+- Filters, caps, truncation warnings and JSON `meta` remain available. `--plain` emits
+  one item per line: `id`, `type`, JSON-quoted `name`, JSON `fields`, separated by tabs.
+  Human output groups fields under items. Neither prints values.
+- Discovery and reference-read failures suppress raw vault diagnostics and parse
+  excerpts, including in verbose mode. They retain the error exit code.
+
 ### `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>`
+### `bwx run --env NAME=<field>:<item> -- <command>` / `--env NAME=<ref>`
 
 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.
@@ -149,12 +199,14 @@ 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 card, else custom field).
+- A discovered `bwx://` ref selects an exact item ID and explicit builtin/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.
 - Several variables from one item cost a single vault read, so group them here rather
   than issuing separate `bwx get` calls.
+- Child stdout/stderr are inherited: use a consumer that does not print its credentials.
 
 ### `bwx attach list <item>`
 
@@ -166,10 +218,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`, `--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`
+Flags: `--type login|note|card`, `--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), card flags (below), `--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.
+`--username`, any `--password-*` or `--totp-*`, and `--uri` require `--type login`; card
+flags require `--type card`. Passing either to another type is an error, not 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.
 
@@ -181,7 +233,22 @@ 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`, `--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`
+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`, card flags and `--rm-number|cvv|cardholder|brand|expiry` (card items only)
+
+### Storing a card
+
+```bash
+bwx create --type card --name "Visa Work" --cardholder "Vladislav Forsh" --brand Visa \
+  --expiry 08/29 --number-stdin --cvv-env CARD_CVV < number.txt
+bwx edit "Visa Work" --expiry 09/31 --cvv-stdin   # merges; other fields untouched
+bwx edit "Visa Work" --rm-cvv --rm-brand
+```
+
+Card flags: `--cardholder`, `--brand` (case-insensitive: Visa, Mastercard, Amex, Discover,
+Diners Club, JCB, Maestro, UnionPay, RuPay, Mir, Other; inferred from the number if
+omitted), `--expiry MM/YY|MM/YYYY` or `--exp-month`/`--exp-year`, `--number[-stdin|-file|-env]`,
+`--cvv[-stdin|-file|-env]`. Number must pass Luhn (`--no-validate` skips it); CVV is 3–4
+digits. Errors never echo the number or CVV.
 
 ### Storing a TOTP secret
 
@@ -266,6 +333,7 @@ even under `--json`; `-q` silences them.
 ## Safety rules
 
 - Never use `--full-items` (or `get item` for discovery) in logged sessions.
+- Discover with `search/find --fields`; pass its `ref` straight to `run --env NAME=<ref>`.
 - 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.

package/src/bw/card-input.ts

@@ -0,0 +1,180 @@
+import { CliError, ExitCode } from "../cli/errors.ts";
+
+/**
+ * Normalizes card values on their way into the vault. Every check runs before
+ * the write, because a mistyped number or expiry is otherwise discovered at the
+ * checkout it was supposed to pay for.
+ *
+ * Errors name the flag and the rule, never the value: a card number or CVV in
+ * an error message ends up in a terminal, a transcript, or a log.
+ */
+
+/** Bitwarden's own brand values, as its clients write and filter on them. */
+export const CARD_BRANDS = [
+	"Visa",
+	"Mastercard",
+	"Amex",
+	"Discover",
+	"Diners Club",
+	"JCB",
+	"Maestro",
+	"UnionPay",
+	"RuPay",
+	"Mir",
+	"Other",
+] as const;
+
+export type CardBrand = (typeof CARD_BRANDS)[number];
+
+/** Spellings people reach for that are not the brand's canonical name. */
+const BRAND_ALIASES: Record<string, CardBrand> = {
+	mc: "Mastercard",
+	americanexpress: "Amex",
+	diners: "Diners Club",
+	cup: "UnionPay",
+};
+
+function brandKey(value: string): string {
+	return value.toLowerCase().replaceAll(/[-_\s]/g, "");
+}
+
+const BRAND_BY_KEY: Record<string, CardBrand> = {
+	...Object.fromEntries(CARD_BRANDS.map((brand) => [brandKey(brand), brand])),
+	...BRAND_ALIASES,
+};
+
+/**
+ * Maps any casing of a brand to the value Bitwarden stores. An unknown brand is
+ * rejected rather than stored as typed: Bitwarden's clients match brand values
+ * exactly, so "visa" would show as no brand at all.
+ */
+export function normalizeBrand(raw: string): CardBrand {
+	const brand = BRAND_BY_KEY[brandKey(raw)];
+	if (!brand) {
+		throw new CliError(
+			`Invalid --brand "${raw}". Valid: ${CARD_BRANDS.join(", ")}`,
+			ExitCode.BadArgs,
+		);
+	}
+	return brand;
+}
+
+/**
+ * IIN prefixes, most specific first so a range nested inside a broader one wins.
+ * Ambiguous prefixes (RuPay shares ranges with Discover and Maestro) are left
+ * out: no brand is better than a confidently wrong one.
+ */
+const BRAND_PREFIXES: Array<[RegExp, CardBrand]> = [
+	[/^3[47]/, "Amex"],
+	[/^3(0[0-5]|[68])/, "Diners Club"],
+	[/^35(2[89]|[3-8])/, "JCB"],
+	[/^220[0-4]/, "Mir"],
+	[/^4/, "Visa"],
+	[/^(5[1-5]|222[1-9]|22[3-9]|2[3-6]|27[01]|2720)/, "Mastercard"],
+	[/^(6011|65|64[4-9]|622(12[6-9]|1[3-9]|[2-8]|9[01]|92[0-5]))/, "Discover"],
+	[/^62/, "UnionPay"],
+	[/^(5018|5020|5038|5893|6304|6759|676[1-3])/, "Maestro"],
+];
+
+/** The brand a normalized number belongs to, or `null` when it is unclear. */
+export function inferBrand(number: string): CardBrand | null {
+	return BRAND_PREFIXES.find(([prefix]) => prefix.test(number))?.[1] ?? null;
+}
+
+export interface CardNumberOptions {
+	/** False skips the Luhn check, for test or private-label numbers. */
+	luhn: boolean;
+}
+
+/**
+ * Strips the spaces and dashes a number is usually written with, then requires
+ * digits and a valid Luhn checksum — the check every real card number passes and
+ * a single mistyped digit fails.
+ */
+export function normalizeCardNumber(
+	raw: string,
+	options: CardNumberOptions,
+): string {
+	const number = raw.replaceAll(/[\s-]/g, "");
+	if (!/^\d{8,19}$/.test(number)) {
+		throw new CliError(
+			"Invalid card number: expected 8–19 digits (spaces and dashes are allowed).",
+			ExitCode.BadArgs,
+		);
+	}
+	if (options.luhn && !passesLuhn(number)) {
+		throw new CliError(
+			"Invalid card number: Luhn checksum failed. Pass --no-validate to store it anyway.",
+			ExitCode.BadArgs,
+		);
+	}
+	return number;
+}
+
+function passesLuhn(number: string): boolean {
+	let sum = 0;
+	for (let i = 0; i < number.length; i++) {
+		let digit = Number(number[number.length - 1 - i]);
+		if (i % 2 === 1) {
+			digit *= 2;
+			if (digit > 9) digit -= 9;
+		}
+		sum += digit;
+	}
+	return sum % 10 === 0;
+}
+
+export function normalizeCvv(raw: string): string {
+	const cvv = raw.trim();
+	if (!/^\d{3,4}$/.test(cvv)) {
+		throw new CliError("Invalid CVV: expected 3 or 4 digits.", ExitCode.BadArgs);
+	}
+	return cvv;
+}
+
+export interface CardExpiry {
+	/** As Bitwarden stores it: the month number, unpadded ("3"). */
+	month: string;
+	/** Always four digits. */
+	year: string;
+}
+
+/** `MM/YY` or `MM/YYYY`; a one-digit month is accepted too. */
+export function parseExpiry(raw: string): CardExpiry {
+	const match = /^\s*(\d{1,2})\s*\/\s*(\d{2}|\d{4})\s*$/.exec(raw);
+	if (!match) {
+		throw new CliError(
+			`Invalid --expiry "${raw}". Use MM/YY or MM/YYYY.`,
+			ExitCode.BadArgs,
+		);
+	}
+	return {
+		month: parseExpMonth(match[1]!, "--expiry"),
+		year: parseExpYear(match[2]!, "--expiry"),
+	};
+}
+
+export function parseExpMonth(raw: string, flag = "--exp-month"): string {
+	const month = /^\s*\d{1,2}\s*$/.test(raw) ? Number(raw) : Number.NaN;
+	if (!Number.isInteger(month) || month < 1 || month > 12) {
+		throw new CliError(
+			`Invalid month in ${flag} "${raw}". Use 1–12.`,
+			ExitCode.BadArgs,
+		);
+	}
+	return String(month);
+}
+
+/**
+ * A two-digit year is expanded to this century: cards are issued for a few
+ * years at most, so `29` cannot reasonably mean 1929.
+ */
+export function parseExpYear(raw: string, flag = "--exp-year"): string {
+	const year = raw.trim();
+	if (/^\d{4}$/.test(year)) return year;
+	if (/^\d{2}$/.test(year)) return `20${year}`;
+	throw new CliError(
+		`Invalid year in ${flag} "${raw}". Use YYYY (or YY).`,
+		ExitCode.BadArgs,
+	);
+}

package/src/bw/discovery.ts

@@ -0,0 +1,59 @@
+import { CliError, ExitCode } from "../cli/errors.ts";
+import { CARD_FIELDS, readCardValue } from "./cards.ts";
+import { builtinReference, customReference, ITEM_ID_RE } from "./references.ts";
+import { BwItemSchema, BwItemType, customFieldTypeLabel, itemTypeLabel } from "./types.ts";
+
+export interface DiscoveredField {
+	kind: "builtin" | "custom";
+	name: string;
+	type: "text" | "hidden" | "boolean" | "totp";
+	ref: string;
+}
+
+export interface ItemDiscovery {
+	id: string;
+	type: string;
+	name: string;
+	fields: DiscoveredField[];
+}
+
+function present(value: unknown): boolean {
+	return typeof value === "string" && value !== "";
+}
+
+/** Explicit allowlist: no spreading raw items or carrying field values forward. */
+export function discoverItem(raw: Record<string, unknown>): ItemDiscovery {
+	const item = BwItemSchema.parse(raw);
+	if (!ITEM_ID_RE.test(item.id)) {
+		throw new CliError("Invalid vault item ID", ExitCode.BwError);
+	}
+	const fields: DiscoveredField[] = [];
+	const addBuiltin = (name: string, type: DiscoveredField["type"], available: boolean) => {
+		if (!available) return;
+		fields.push({ kind: "builtin", name, type, ref: builtinReference(item.id, name) });
+	};
+	addBuiltin("notes", "text", present(item.notes));
+	if (item.type === BwItemType.Login) {
+		addBuiltin("username", "text", present(item.login?.username));
+		addBuiltin("password", "hidden", present(item.login?.password));
+		addBuiltin("uri", "text", present(item.login?.uris?.[0]?.uri));
+		addBuiltin("totp", "totp", present(item.login?.totp));
+	}
+	if (item.type === BwItemType.Card && item.card) {
+		for (const name of CARD_FIELDS) {
+			const type = name === "number" || name === "cvv" ? "hidden" : "text";
+			addBuiltin(name, type, readCardValue(item.card, name) !== null);
+		}
+	}
+	for (const [index, field] of (item.fields ?? []).entries()) {
+		const type = customFieldTypeLabel(field.type);
+		if (type === undefined) continue; // Linked/unknown types have no supported value reader.
+		fields.push({
+			kind: "custom",
+			name: field.name,
+			type,
+			ref: customReference(item.id, index, field.name),
+		});
+	}
+	return { id: item.id, type: itemTypeLabel(item.type), name: item.name, fields };
+}