@did-btcr2/cli 0.14.0 → 0.16.0

package/README.md

@@ -36,11 +36,13 @@ npx @did-btcr2/cli resolve -i did:btcr2:k1qq...
 
 | Command | Alias | Description |
 |---|---|---|
+| `init` | - | Set up the btcr2 home: create the directory, a default config, and establish the keystore |
 | `create` | - | Create an identifier and initial DID document |
 | `resolve` | `read` | Resolve a DID document |
 | `update` | - | Update a DID document (signs via the keystore) |
 | `deactivate` | `delete` | Deactivate a DID permanently (signs via the keystore) |
-| `key` | - | Manage keypairs in the encrypted keystore |
+| `key` | - | Manage keypairs in the keystore |
+| `keystore` | - | Establish, inspect, and re-key the keystore |
 | `config` | - | Read and write CLI configuration |
 | `profile` | - | Manage configuration profiles |
 | `completion` | - | Print a shell completion script |
@@ -87,16 +89,38 @@ Required flags: `-s/--source-document`, `--source-version-id`, `-p/--patches`, `
 | `-m, --verification-method-id <id>` | DID document verification method ID |
 | `-b, --beacon-id <json>` | Beacon ID as a JSON string |
 | `--publish-to-cas <mode>` | Publish update artifacts to a writable CAS before broadcast: `auto`, `always`, or `never` (default: `never`). See [Publishing updates to CAS](#publishing-updates-to-cas) |
+| `--fee-rate <satsPerVByte>` | Fee rate in sats/vByte for the beacon transaction (default: `5`). Raise it under congestion so the transaction confirms (also `BTCR2_FEE_RATE`, profile `btc.feeRate`) |
+| `--change-address <address>` | Send transaction change to this address instead of the beacon address, so a DID's announcements are not linked on-chain (profile `btc.changeAddress`) |
 
 ### deactivate (alias: delete)
 
 Permanently deactivates a DID. This is irreversible. Deactivation applies the `{ "op": "add", "path": "/deactivated", "value": true }` patch and routes through the same signed-update path as `update`, so it also signs via the keystore.
 
-Required flags: `-s/--source-document`, `--source-version-id`, `-m/--verification-method-id`, `-b/--beacon-id`. Optional: `--publish-to-cas <mode>` (same as `update`).
+Required flags: `-s/--source-document`, `--source-version-id`, `-m/--verification-method-id`, `-b/--beacon-id`. Optional: `--publish-to-cas <mode>`, `--fee-rate <satsPerVByte>`, `--change-address <address>` (same as `update`).
+
+### init
+
+`btcr2 init` is the one-command setup: it creates the btcr2 home directory, writes a default config if none exists, and establishes the keystore if none exists. It is idempotent (existing files are left untouched unless `--force`).
+
+| Flag | Description |
+|---|---|
+| `--dev` | Establish an **unencrypted** dev keystore (plaintext keys, no passphrase). Testnet/regtest only; mainnet operations are refused |
+| `--force` | Re-create the config and keystore even if they already exist |
+
+By default `init` establishes an **encrypted** keystore and prompts (with confirmation) for a passphrase up front, so the first `key generate` never seals the keystore under an unconfirmed, mistyped passphrase. Supply the passphrase non-interactively with `BTCR2_KEYSTORE_PASSPHRASE` or `--passphrase-file` for scripted setup.
+
+The workshop happy path:
+
+```bash
+btcr2 init --dev --network mutinynet   # (or: btcr2 init  for an encrypted keystore)
+btcr2 key generate --set-active
+btcr2 create --network mutinynet
+# ...fund the beacon, resolve, update, deactivate...
+```
 
 ### key
 
-Manage keypairs in the encrypted keystore. All subcommands operate offline (no Bitcoin connection).
+Manage keypairs in the keystore. All subcommands operate offline (no Bitcoin connection).
 
 | Subcommand | Alias | Description |
 |---|---|---|
@@ -110,6 +134,18 @@ Manage keypairs in the encrypted keystore. All subcommands operate offline (no B
 
 A key reference is a full URN, a unique `name` tag, or a unique fingerprint prefix.
 
+### keystore
+
+Establish, inspect, and re-key the keystore. These operate on the keystore file directly (no Bitcoin connection).
+
+| Subcommand | Alias | Description |
+|---|---|---|
+| `keystore init` | - | Establish the keystore (encrypted by default; prompts and confirms the passphrase). `--dev` creates an unencrypted dev keystore; `--force` re-establishes an existing one (discards its keys) |
+| `keystore status` | - | Show the resolved path, protection mode (`encrypted`/`dev`/`absent`), whether a passphrase is established, and the key count. Never decrypts or prompts |
+| `keystore change-passphrase` | `passwd` | Re-seal every key under a new passphrase (encrypted keystores only). Prompts for the current passphrase, then a new one (with confirmation) |
+
+**Encrypted vs dev keystores.** An encrypted keystore seals each secret with argon2id + XChaCha20-Poly1305 under one passphrase, and records a verifier so a mistyped passphrase fails loudly (with `Incorrect passphrase`) instead of sealing a key under an unknown or divergent passphrase. A **dev keystore** (`--dev`) stores secrets in plaintext and never prompts: it is for disposable testnet/regtest keys only, and the CLI **hard-refuses** to sign or generate a mainnet (`bitcoin`) key with one.
+
 ### config
 
 Read and write CLI configuration.
@@ -117,10 +153,14 @@ Read and write CLI configuration.
 | Subcommand | Alias | Description |
 |---|---|---|
 | `config init` | - | Create a default config file with one profile per network. `--force` overwrites |
-| `config get [path]` | - | Print a value at a dotted path, or the whole config |
-| `config set <path> <value>` | - | Set a value at a dotted path (value parsed as JSON when valid, else a string) |
+| `config get [path]` | - | Print a value at a dotted path, or the whole config. Secret values are redacted; `--show-secrets` reveals them |
+| `config set <path> <value>` | - | Set a value at a dotted path (value parsed as JSON when valid, else a string). An invalid enum for a known key is rejected; an unknown path warns but writes |
 | `config unset <path>` | - | Delete a value at a dotted path |
-| `config list` | `ls` | Print the entire config file |
+| `config list` | `ls` | Print the entire config file. Secret values are redacted; `--show-secrets` reveals them |
+| `config validate` | - | Report unknown keys, invalid enum values, and an unsupported schema version |
+| `config effective` | - | Print the resolved connection config with per-value provenance (`flag`/`env`/`file`/`default`). `-n, --network <n>` selects the network; `--show-secrets` reveals the RPC password |
+| `config path` | - | Print the resolved home directory, config-file, and keystore paths |
+| `config doctor` | - | Probe reachability of the resolved endpoints (read-only; touches the network). `-n, --network <n>` selects the network |
 
 ### profile
 
@@ -214,18 +254,24 @@ Override precedence, highest wins: CLI flags, then environment variables, then c
 | Flag | Description |
 |---|---|
 | `-v, --version` | Output the current version |
-| `-o, --output <format>` | Output format: `json` or `text` (default: `text`) |
+| `-o, --output <format>` | Output format: `json` or `text` (default: config `defaults.output`, else `text`) |
 | `--verbose` | Verbose output |
 | `--quiet` | Suppress non-essential output |
-| `-c, --config <path>` | Path to config file (default: `$XDG_CONFIG_HOME/btcr2/config.json`) |
+| `--home <dir>` | btcr2 home directory holding `config.json` + `keystore.json` (default: `~/.btcr2`, `%LOCALAPPDATA%\btcr2` on Windows; overrides `$BTCR2_HOME`) |
+| `-c, --config <path>` | Path to config file (default: `<home>/config.json`) |
 | `--profile <name>` | Config profile name (default: auto-detected from network) |
 | `--btc-rest <url>` | Override Bitcoin REST endpoint (Esplora API) |
 | `--btc-rpc-url <url>` | Override Bitcoin Core RPC endpoint |
 | `--btc-rpc-user <user>` | Bitcoin Core RPC username |
-| `--btc-rpc-pass <pass>` | Bitcoin Core RPC password |
+| `--btc-rpc-pass <pass>` | Bitcoin Core RPC password (accepts an `env:<VAR>` or `file:<path>` secret reference) |
+| `--btc-rpc-wallet <name>` | Bitcoin Core wallet name for wallet-scoped RPCs (`/wallet/<name>`) |
+| `--btc-rpc-header <header>` | Extra Bitcoin Core RPC header `"Key: Value"` (repeatable) |
+| `--btc-rest-header <header>` | Extra Bitcoin REST header `"Key: Value"` (repeatable), e.g. an API key |
+| `--btc-timeout <ms>` | Bitcoin REST/RPC request timeout in milliseconds (default: unbounded) |
 | `--cas-gateway <url>` | IPFS HTTP gateway for CAS reads (read-only) |
 | `--cas-rpc-url <url>` | IPFS HTTP RPC endpoint for a writable CAS (reads + writes; enables `--publish-to-cas`) |
-| `--keystore <path>` | Path to the keystore file (default: `$XDG_DATA_HOME/btcr2/keystore.json`) |
+| `--cas-timeout <ms>` | CAS request timeout in milliseconds (default: `30000`; `0` disables) |
+| `--keystore <path>` | Path to the keystore file (default: `<home>/keystore.json`) |
 | `--passphrase-file <path>` | Read the keystore passphrase from a file (unattended use) |
 | `--signing-key <ref>` | Key for create/update/deactivate signing: a URN, fingerprint prefix, or name |
 
@@ -237,35 +283,78 @@ Override precedence, highest wins: CLI flags, then environment variables, then c
 | `BTCR2_BTC_RPC_URL` | `--btc-rpc-url` |
 | `BTCR2_BTC_RPC_USER` | `--btc-rpc-user` |
 | `BTCR2_BTC_RPC_PASS` | `--btc-rpc-pass` |
+| `BTCR2_BTC_RPC_PASS_FILE` | file whose contents are the RPC password |
 | `BTCR2_CAS_GATEWAY` | `--cas-gateway` |
 | `BTCR2_CAS_RPC_URL` | `--cas-rpc-url` |
+| `BTCR2_BTC_TIMEOUT` | `--btc-timeout` |
+| `BTCR2_CAS_TIMEOUT` | `--cas-timeout` |
+| `BTCR2_FEE_RATE` | `--fee-rate` |
+| `BTCR2_OUTPUT` | `-o, --output` |
+| `BTCR2_HOME` | `--home` |
+| `BTCR2_KEYSTORE_PASSPHRASE` | keystore passphrase (unattended use) |
+
+### Home directory
+
+The CLI keeps its config and keystore side by side in one home directory, resolved as `--home <dir>`, then `$BTCR2_HOME`, then the platform default: `~/.btcr2` on Linux/macOS and `%LOCALAPPDATA%\btcr2` on Windows. Both files live directly under it (`<home>/config.json`, `<home>/keystore.json`); `btcr2 config path` prints the resolved locations. `--config` and `--keystore` still override each file individually, so the historical XDG split can be reproduced explicitly.
 
 ### Config file
 
-Default location: `$XDG_CONFIG_HOME/btcr2/config.json` (falls back to `~/.config/btcr2/config.json`).
+Default location: `<home>/config.json`. A malformed config file fails loudly (the CLI never silently falls back to public endpoints, and never overwrites an unparseable file).
 
-Profiles are matched by network name when `--profile` is not specified. For example, resolving a regtest DID automatically selects the `"regtest"` profile.
+Profiles are matched by network name when `--profile` is not specified. For example, resolving a regtest DID automatically selects the `"regtest"` profile. A profile that is not named after a network can declare its network with a `network` field.
 
 ```json
 {
+  "schemaVersion": 1,
+  "defaults": {
+    "profile": "production",
+    "network": "bitcoin",
+    "output": "text"
+  },
   "profiles": {
     "regtest": {
       "btc": {
         "rest": "http://localhost:3000",
         "rpcUrl": "http://localhost:18443",
         "rpcUser": "polaruser",
-        "rpcPass": "polarpass"
+        "rpcPass": "polarpass",
+        "wallet": "primary",
+        "feeRate": 5,
+        "timeoutMs": 30000
       }
     },
-    "bitcoin": {
-      "btc": { "rest": "https://my-mempool/api" },
-      "cas": { "gateway": "https://ipfs.io", "rpcUrl": "http://127.0.0.1:5001" }
+    "production": {
+      "network": "bitcoin",
+      "btc": {
+        "rest": "https://my-mempool/api",
+        "headers": { "Authorization": "Bearer <api-key>" },
+        "feeRate": 20
+      },
+      "cas": { "gateway": "https://ipfs.io", "rpcUrl": "http://127.0.0.1:5001", "timeoutMs": 30000 },
+      "identity": { "keystore": "/secure/prod-keystore.json", "default": "did:btcr2:...#key-0" }
     }
   }
 }
 ```
 
-`cas.gateway` is a read-only IPFS HTTP gateway (used for reads). `cas.rpcUrl` is an IPFS HTTP RPC endpoint that supports writes; configure it to enable `--publish-to-cas`. When both are set, `rpcUrl` takes precedence.
+Field notes:
+
+- **`defaults`**: `profile` selects the active profile; `network` fixes the network `create` encodes when `-n` is absent; `output` sets the default output format. `schemaVersion` is stamped on every write; a file written by a newer CLI is refused.
+- **`btc`**: `rest`/`rpcUrl`/`rpcUser`/`rpcPass` are endpoints and credentials; `wallet` targets a Bitcoin Core wallet (`/wallet/<name>`); `headers`/`rpcHeaders` add REST/RPC headers; `feeRate` (sats/vByte), `changeAddress`, and `timeoutMs` set broadcast and request behavior. The RPC url, user, and pass are resolved as one atomic unit, so a URL from a higher-precedence layer never inherits credentials from a lower one.
+- **`cas`**: `gateway` is a read-only IPFS HTTP gateway; `cas.rpcUrl` is a writable IPFS HTTP RPC endpoint (enables `--publish-to-cas`; `rpcUrl` wins over `gateway`); `timeoutMs` bounds CAS operations (`0` disables).
+- **`identity`**: `keystore` points the profile at its own keystore file, and `default` is the profile's default signing key. Both fall **below** the corresponding `--keystore` / `--signing-key` flags.
+
+Use `config validate` to check a file, and `config effective` to see the resolved values with their provenance.
+
+### RPC password and secrets
+
+`config get` and `config list` redact secret-looking values (RPC password and any `pass`/`secret`/`token` key) by default; pass `--show-secrets` to reveal them.
+
+An `rpcPass` written directly into `config.json` is stored in cleartext (the file is mode 0600 but not encrypted). For anything sensitive, keep the secret out of the file with a reference or an RPC-URL-embedded credential:
+
+- `"rpcPass": "env:MY_RPC_PASS"` reads the password from the `MY_RPC_PASS` environment variable.
+- `"rpcPass": "file:/run/secrets/rpc-pass"` reads it from a file (a single trailing newline is trimmed).
+- `BTCR2_BTC_RPC_PASS_FILE=/run/secrets/rpc-pass` names a file to read when no other RPC password source applies.
 
 ### Defaults