@candledottv/cli 0.9.2 → 0.11.0

package/README.md

@@ -7,7 +7,7 @@ health from the terminal. Zero runtime dependencies; the whole thing is one self
 ## Quick start
 
 ```
-Install the Candle CLI (macOS or Linux):
+Install the Candle CLI (macOS 13 or later, or Linux):
 
     curl -fsSL https://candle.tv/install.sh | bash
 
@@ -24,6 +24,8 @@ login` on its own does just the authorization step.
 
 The npm package `@candledottv/cli` stays published for CI, programmatic use, and Windows until
 `install.ps1` ships; `npx -y @candledottv/cli@latest <command>` runs it once without installing.
+It is also the way in on macOS 12 or earlier: the release binaries need macOS 13, and `install.sh`
+and Homebrew refuse an older Mac rather than install a binary not built for it.
 
 ### No-npm fallback
 
@@ -57,6 +59,10 @@ node packages/cli/dist/index.js auth login
 | `candle keys create [--scopes <a,b,c>] [--label <name>] [--expires-in <days>] [--tx-limit <usd> [--reset daily\|weekly\|monthly\|never]]` | Creates a new API key and prints the plaintext exactly once, with the same optional name, expiration, and USD transaction limit the portal's create form takes. Stored locally only if the CLI does not already hold a working key. |
 | `candle keys revoke <prefix>` | Revokes an API key by prefix. Revoking the CLI's own stored key also clears it locally. |
 | `candle wallets` | Shows the account's embedded (launch) wallets and any linked wallets, using the API key, with a `Signer` column saying whether this machine holds each linked wallet's signing key. |
+| `candle vault init\|status\|new-key\|phrase show\|restore` | The encrypted local vault, `vault.enc`. `init` creates it with a passphrase factor and a 24-word recovery phrase, `new-key` derives a key inside it, `phrase show` displays the phrase on a terminal (never in `--json`, a log or a pipe), and `restore --phrase` rebuilds the derived keys on another machine. No key ever leaves the vault to reach Candle. See [The vault](https://docs.candle.tv/developers/cli#the-vault). |
+| `candle vault factor list\|add passphrase\|add security-key\|add touch-id\|add passkey\|remove`, `vault backup --to <path>`, `vault verify-backup <path>` | What can open the vault, and proving a copy of it works: `backup` verifies the copy in full before reporting (a copy is sealed to the passphrase envelope unless it goes to a recognised local disk or removable drive, so a cloud folder and any path the CLI cannot place are both sealed unless `--accept-shared-domain` is passed), and `verify-backup` re-checks an existing one against this vault's key and address set. `add security-key` enrolls a FIDO2 security key (CTAP2 `hmac-secret`, user-verified with the key's PIN or biometric) through the bundled `candle-fido2` helper; one key is not a recoverable factor, two keys are a pair, and the passphrase stays the recovery floor. Every vault command then takes `--factor <id\|passphrase\|security-key>` to say which envelope opens it and `--device <id>` to name the key when several are attached. |
+| `candle vault transfer\|promote\|fund\|demote\|export-key` | Moving value and authority. `transfer` and `fund` sign locally from a vault key after showing the decoded transaction; `promote` turns a vault key into a delegated TEE wallet (fresh, or the key's own address after a typed warning) and `demote` sweeps it back; `export-key` is the one ceremony that writes a single private key to a file you name. |
+| `candle vault import-legacy --tee`, `candle vault retire-legacy` | Moves an existing `tee-wallets.enc` into the vault without deleting it, then retires the old file once the vault holds everything and a backup has been verified. |
 | `candle tee new\|enable\|fund\|status\|disable\|sweep` | A dedicated, capped TEE wallet for one agent: the CLI generates the key and seals it locally in `tee-wallets.enc`, `enable` delegates it to this profile's API key with a pinned sweep vault, `fund` prints what your vault signs, and `disable` then `sweep` stop the agent and move everything back to the vault, signed locally. Solana only. See [TEE wallets](https://docs.candle.tv/developers/cli#tee-wallets). |
 | `candle profile list` | Lists profiles on this machine, with cached accounts. |
 | `candle profile add <name> --api-url <url>` | Creates a profile before authenticating it. |
@@ -123,6 +129,43 @@ guarantee is unconfirmed: a wallet stop whose remote enforcement is still pendin
 enabled without verified signing authority, or a sweep that left a residual). Treat `3` as not
 done: follow the printed next step, usually re-running the same command.
 
+A generated vault passphrase is shown once on the terminal and never inside a JSON value, so
+`vault init` and `vault factor add passphrase` under `--json` take `--own-passphrase` (typed at a
+hidden prompt, nothing shown) and refuse the generated form with exit `2`. Prompts themselves are
+rendered on stderr, so a command that unlocks a vault on a terminal still leaves stdout as one
+JSON value. A security key's PIN is read the same way, by the CLI on its own hidden prompt, and
+reaches the `candle-fido2` helper only inside a request piped to it; the helper never reads the
+terminal and the PIN never appears in any output.
+
+The security key factor needs the `candle-fido2` helper beside the `candle` binary, which the
+installer script and Homebrew put there (Homebrew also installs `libfido2`, which the helper loads
+at run time; the installer names the package to add), and it needs libfido2's udev rule on Linux.
+The npm package ships no native helper: there the factor is refused with `VAULT_HELPER_MISSING`
+until a release build's `candle-fido2` is installed and `CANDLE_FIDO2_HELPER` points at it. No
+other factor is ever substituted for one that is refused.
+
+The Touch ID factor (`candle vault factor add touch-id`; not yet released) needs
+the signed `candle-enclave.app` helper, which the darwin tarball, the installer script and Homebrew
+place beside `candle` once a release ships it; a release cut before Apple's approval ships no
+helper and the CLI refuses the factor with a typed code that says so. The CLI verifies the
+helper's code signature with `/usr/bin/codesign` before trusting it, and `CANDLE_ENCLAVE_HELPER`
+points at a bundle elsewhere. The factor opens the vault on one Mac only and is never a recovery
+factor; the passphrase remains the recovery floor.
+
+The synced passkey factor (`candle vault factor add passkey`; not yet released)
+runs through the same signed helper on macOS 15 or later, and needs the helper's
+associated-domains entitlement for `webcredentials:cli.candle.tv` with an embedded provisioning
+profile, plus an `apple-app-site-association` served at
+`https://cli.candle.tv/.well-known/apple-app-site-association` (status 200, no redirect,
+`Content-Type: application/json`, `{"webcredentials":{"apps":["<TEAM ID>.tv.candle.cli.enclave"]}}`).
+Each missing piece is a typed refusal before any passkey sheet, and the refusal names what must be
+served. The passkey follows the Apple account, so it is a recoverable factor; two are one factor,
+and a copy of the vault is sealed to the passphrase envelope by default unless it goes to a
+recognised local disk or removable drive, so that one account never holds
+both the blob and a factor that opens it. iCloud Drive and other cloud folders are sealed for that
+reason, and so is any path the CLI cannot place, since it cannot tell whether that path syncs to an
+account; `--accept-shared-domain` writes the full copy and the acceptance is recorded.
+
 The failure envelope is stable:
 
 ```json