@xyo-network/wallet-xl1-cli 0.1.20 → 0.1.22

package/README.md

@@ -17,7 +17,7 @@ The Aries CLI uses this same package for `aries wallet ...`, so the standalone a
 
 ### Prerequisites
 
-- Node.js `>=18.17.1`
+- Node.js `>=22.19.0`
 - A package manager such as `npm`, `pnpm`, or `yarn`
 
 ### Global Install
@@ -59,6 +59,58 @@ aries wallet balance 0
 aries wallet send 0x0000000000000000000000000000000000000000 1.25 --milli --json
 ```
 
+## Requester-scoped Node signing
+
+The supported `@xyo-network/wallet-xl1-cli/signing` entry exposes public wallet
+summaries and short-lived, account-bound signing sessions. Install the package
+locally with its `@xyo-network/xl1-sdk` peer. Consumers select the requester ID,
+exact wallet ID, derivation offset, expected account, chain ID, and independently
+verified genesis hash. The wallet itself confirms that selection and prompts on
+the trusted terminal for its password; this API does not accept a password,
+mnemonic, root wallet, or caller-provided signer.
+
+```ts
+import { listSigningWallets, openWalletSigningSession } from '@xyo-network/wallet-xl1-cli/signing'
+
+const wallets = listSigningWallets()
+const session = await openWalletSigningSession(selection)
+try {
+  const snapshot = await session.snapshot()
+  const signed = await session.signTransaction({ requestId, transaction })
+  // Persist signed bytes in the participant publication journal before broadcasting.
+} finally {
+  await session.close()
+}
+```
+
+Here `selection` is the complete explicit binding and `transaction` is an SDK
+unsigned hydrated transaction. The session signs without publishing bodies or
+broadcasting. It supports secp256k1 wallets; post-quantum transaction signing is
+not qualified. Sessions expire within five minutes. Lock, close, password
+replacement, and wallet replacement revoke authority for new signing.
+
+The wallet persists request intent and encrypted signed results in `signing.json`
+under its existing guarded store lease. Retrying the same request returns the
+same bytes. `signingOutcome(requestId)` recovers a retained result through a fresh
+authorized session with the same complete binding. An uncertain intent blocks
+new same-account signing; an error, timeout, or `4001` is never proof that no
+signature exists. Existing CLI `tx sign` and `send` use this same signing ledger,
+with publication remaining a separate command step. Legacy offline signing has
+an explicitly unasserted genesis scope; it cannot authorize public requester
+sessions. This does not reconstruct pre-upgrade or external-key signing history.
+
+Run the isolated packed public import, type, real terminal prompt, and process
+recovery fixture from the repository root after both wallet package builds:
+
+```sh
+node packages/wallet-cli/scripts/verifySigningPacked.mjs /absolute/fresh/evidence-directory
+```
+
+The terminal fixture currently qualifies macOS. It creates only a temporary
+public deterministic wallet. Its strict consumer type check uses `skipLibCheck`;
+the full dependency declaration check is retained separately because upstream SDK
+declarations currently fail that broader check.
+
 ## Wallet Storage
 
 Wallet CLI data is stored under `~/.xl1/wallet/cli` by default.
@@ -67,7 +119,8 @@ Wallet CLI data is stored under `~/.xl1/wallet/cli` by default.
 | --- | --- |
 | `XL1_WALLET_HOME` | Overrides the wallet storage directory. |
 | `ARIES_WALLET_HOME` | Legacy fallback storage override. Used only when `XL1_WALLET_HOME` is not set. |
-| `ARIES_WALLET_PASSWORD` | Supplies the wallet password for non-interactive runs and tests. |
+| `ARIES_WALLET_PASSWORD` | Supplies the wallet password. A nonempty value is validated before any cached session is used. For a new store, it sets the initial password. |
+| `ARIES_WALLET_NON_INTERACTIVE=1` | Refuses terminal password and recovery-phrase prompts. Private-key access requires an unlocked session or `ARIES_WALLET_PASSWORD`; import requires `--phrase-stdin` or `--phrase`. |
 
 Wallet seed phrases are encrypted at rest. Commands that need private key access prompt for the wallet password unless `ARIES_WALLET_PASSWORD` is set.
 
@@ -97,10 +150,45 @@ xl1-wallet network use xl1-sequence
 Add a local or custom network:
 
 ```sh
-xl1-wallet network add local http://127.0.0.1:8080/rpc --label "Local XL1" --chain-id 0x1234
+xl1-wallet network add local http://127.0.0.1:8080/rpc --label "Local XL1" --chain-id 1234
 xl1-wallet network use local
 ```
 
+Adding a network preserves the current selection and rejects duplicate IDs.
+New IDs must be nonblank, contain no control characters, fit within 256 UTF-8
+bytes, and not begin with `-`. Optional labels are preserved exactly and may
+contain up to 1024 UTF-8 bytes. Optional chain IDs use the XL1 protocol's
+nonempty lowercase hexadecimal form without a `0x` prefix; there is no fixed
+length requirement. The chain ID is stored metadata: adding a network does not
+probe the endpoint or verify its chain.
+
+For endpoints containing path or query credentials, pass the complete URL via
+private stdin instead of a positional argument. Stdin must contain only the URL
+as UTF-8, with no trailing newline, and is limited to 16 KiB. URLs must be complete
+HTTP or HTTPS URLs without controls or fragments. Local HTTP endpoints are
+supported. URL username/password information is rejected because the RPC fetch
+transport does not support it.
+
+```sh
+printf '%s' "$RPC_URL" | xl1-wallet network inspect-add custom \
+  --rpc-url-stdin --label="Custom XL1" --chain-id=1234 --json
+printf '%s' "$RPC_URL" | xl1-wallet network add custom \
+  --rpc-url-stdin --label="Custom XL1" --chain-id=1234 \
+  --expected-state="$REVIEWED_STATE_HASH" --json
+```
+
+`inspect-add` validates the proposed entry and returns its ID, label, optional
+chain ID, current active ID, canonical wallet root, and `stateHash`. Use that
+hash as `REVIEWED_STATE_HASH` for the corresponding add. Inspection does not
+create `networks.json`; the add writes defaults and the custom entry atomically
+under the wallet store lease. If any wallet file changes after review, the
+guarded add fails and must be reviewed again. `--rpc-url-stdin` and a positional
+URL are mutually exclusive.
+
+Network list and add support `--json`. Network summaries and
+success messages omit the entire RPC URL, including its hostname. The URL is
+stored in the private wallet configuration for RPC use.
+
 Remove a custom network:
 
 ```sh
@@ -115,15 +203,16 @@ xl1-wallet network remove local
 | --- | --- |
 | `xl1-wallet create` | Create a new wallet. |
 | `xl1-wallet import` | Import a recovery phrase. |
-| `xl1-wallet export` | Print a wallet recovery phrase after password confirmation. |
+| `xl1-wallet export` | Print a wallet recovery phrase using a password or unlocked session. |
 | `xl1-wallet list` | List wallets in the current wallet home. |
 | `xl1-wallet use <id>` | Set the active wallet. |
 | `xl1-wallet rename <id> <label>` | Rename a wallet. |
-| `xl1-wallet remove <id>` | Remove a wallet from local storage. |
-| `xl1-wallet reset` | Delete local wallet CLI data after confirmation. |
+| `xl1-wallet remove [id]` | Authenticate and remove a wallet; `--wallet-id` targets an exact ID. |
+| `xl1-wallet reset` | Delete known wallet files after confirmation, preserving unrelated files. |
 | `xl1-wallet unlock` | Cache an encrypted wallet session for a limited time. |
 | `xl1-wallet lock` | Clear the cached wallet session. |
-| `xl1-wallet password change` | Change the active wallet password. |
+| `xl1-wallet password change` | Change the shared password for every wallet in the store. |
+| `xl1-wallet lifecycle preview --json` | Inspect the canonical store path, state fingerprint, wallets, and known files. |
 
 Examples:
 
@@ -135,17 +224,63 @@ xl1-wallet import --label quant-recovery --phrase "..." --algorithm ml-dsa-65
 xl1-wallet list
 xl1-wallet use <wallet-id>
 xl1-wallet export --id <wallet-id>
+xl1-wallet export --wallet-id <exact-wallet-id> --json
 ```
 
 `create` and `import` default to `--algorithm secp256k1`. Use `--algorithm ml-dsa-65` for `QuantHDWallet` wallets, which derive `qm65...` bech32m addresses. Wallet-signed JWT commands require secp256k1 because ML-DSA-65 does not yet have a standardized JOSE algorithm.
-Wallet labels must be unique. If `create` is run without `--label`, the CLI uses the first available `wallet#` label, starting with `wallet0`.
+Wallet labels must be unique, nonblank, and free of NUL characters. Other label text, including surrounding spaces, is preserved. If `create` is run without `--label`, the CLI uses the first available `wallet#` label, starting with `wallet0`.
+Commands accepting a wallet ID or label prefer an exact ID match before looking
+for a matching label.
+
+For unattended imports, `--phrase-stdin` reads raw UTF-8 from standard input
+until EOF, up to 16 KiB, and trims surrounding whitespace. It is mutually
+exclusive with `--phrase`. The algorithm, label, and recovery phrase are
+validated before the command initializes a password or stores a wallet.
+
+`export --wallet-id` accepts only an exact stored ID and cannot be combined
+with `--id`. The existing `--id` option also accepts labels; omitting both
+options reveals the active wallet.
+
+`create --json` and `export --json` emit only
+`{id, label, algorithm, mnemonic}` to stdout. This output contains the recovery
+phrase. `import --json` emits only `{id, label, algorithm}` and does not include
+the phrase. Text output remains the default.
+
+Password change requires the current password even with an unlocked session.
+`ARIES_WALLET_PASSWORD` supplies only that current password. For automation,
+`password change --new-password-stdin --json` reads the new password as raw UTF-8
+until EOF, preserving all whitespace, with a 4096-byte limit and no NUL
+characters. Its JSON result is `{changed: true}`. Interactive mode asks for and
+confirms the new password separately. Rotation clears the cached session.
+
+`remove --wallet-id=<exact-id> --json` returns `{id, label, removed: true}`.
+The named selector cannot be combined with the positional ID/label. A supplied
+wrong password fails even if an unlocked session exists.
+
+Password change, removal, and reset accept `--expected-state=<stateHash>` from
+`lifecycle preview --json`. The CLI checks this fingerprint under its filesystem
+lease before writing; a changed store requires a new review. Preview returns
+`{root, stateHash, wallets, files}` without credentials. If wallet metadata is
+corrupt, `wallets` is `null` with a `metadataError`, so reset can still be reviewed.
+
+Updated CLI processes share a canonical-path filesystem lease. Overlapping
+operations report a busy store; a killed owner's lease expires after 30 seconds.
+Older CLI versions and other programs that ignore the lease are not coordinated.
+Password rotation, removal, and reset commit a durable roll-forward journal
+before replacing data files. The journal contains encrypted wallet records and
+password-verifier metadata, never plaintext passwords or recovery phrases.
+The next leased operation completes a valid pending transaction before reading
+the store. After an interrupted rotation, try the new password first. Individual
+files and journals are limited to 16 MiB. File data is synced; directory syncing
+is best effort on Windows where unsupported. A corrupt or unrecoverable journal
+blocks operations, including reset: preserve its files for repair.
 
 ### Accounts
 
 | Command | Description |
 | --- | --- |
 | `xl1-wallet account derive <offset>` | Derive and store an account at an offset. |
-| `xl1-wallet account list` | List stored accounts for the active wallet. |
+| `xl1-wallet account list [--wallet <id-or-label>]` | List stored accounts for the active or specified wallet. |
 | `xl1-wallet account show <offset>` | Show a derived account address. |
 | `xl1-wallet account label <offset> <label>` | Label an account. |
 | `xl1-wallet account remove <offset>` | Remove a stored account record. |
@@ -156,8 +291,17 @@ Examples:
 xl1-wallet account derive 0 --label main
 xl1-wallet account show 0
 xl1-wallet account list
+xl1-wallet account derive 4 --wallet-id <wallet-id> --label savings
 ```
 
+Account `show`, `derive`, `label`, and `remove` accept `--wallet-id` to target an
+exact stored wallet without changing the active wallet. Labels are not accepted
+by this option. Omitting it keeps the active-wallet default. Desktop account
+changes require an explicit wallet ID so a reviewed change stays attached to
+the intended wallet. Account removal only removes address-book metadata;
+the key remains derivable and funds are unaffected. Account labeling validates
+the derivation path before saving it.
+
 ### Balances And Transfers
 
 | Command | Description |
@@ -276,6 +420,60 @@ xl1-wallet backup import wallet-metadata.json
 xl1-wallet reset
 ```
 
+Metadata backups retain the version 1 `network.xyo.wallet.backup` format. They
+contain address-book offsets and labels, and contact addresses, labels, and
+timestamps. They do not contain recovery phrases, passwords, session credentials,
+or network configuration. Imports merge metadata: incoming defined account labels
+and contact labels win, existing account labels survive when incoming labels are omitted, and existing
+contact creation timestamps are preserved. Contact update timestamps never move
+backward when importing an older backup.
+
+Review an import or export before applying it:
+
+```sh
+xl1-wallet backup inspect wallet-metadata.json --direction=import --json
+xl1-wallet backup inspect wallet-metadata.json --direction=export --json
+```
+
+The JSON result is `{root, stateHash, path, fileStateHash, exists, addressBooks,
+accounts, contacts}`. `root` and `path` are canonical absolute paths. Counts refer
+to incoming backup entries for import, or the stored metadata to export. The
+inspection exposes only paths, counts, existence, and hashes. To require exactly
+the reviewed wallet and file states, pass both hashes to the subsequent command:
+
+```sh
+xl1-wallet backup import wallet-metadata.json \
+  --expected-state=<stateHash> --expected-file-state=<fileStateHash> --json
+xl1-wallet backup export wallet-metadata.json --overwrite \
+  --expected-state=<stateHash> --expected-file-state=<fileStateHash> --json
+```
+
+Import returns `{imported: true, addressBooks, accounts, contacts}`; export returns
+`{exported: true, addressBooks, accounts, contacts}`. Existing export destinations
+require `--overwrite`. New exports never overwrite a file created concurrently.
+Exports use private `0600` temporary files, fsync, and atomic publication. Imports
+commit address books and contacts together through the wallet recovery journal
+and never modify their source backup. Cooperating CLI processes coordinate by
+wallet root and export destination, including exports from different wallet roots.
+
+Files must be regular files of at most 16 MiB, with one filesystem link. Symlinks,
+directories, special files, wallet storage files, and wallet transaction or lease
+paths are rejected. The parent directory must already exist. Version 1 schemas
+and fields are validated strictly; unknown entries, duplicate books/accounts or
+contacts, invalid legacy or quant addresses, and prototype keys are rejected.
+Labels preserve every string accepted by existing version 1 authoring commands,
+including empty, multiline, and long values, within the overall file size limit.
+Offsets use decimal HD path segments up to `2147483647`, optional hardened
+apostrophes and `m/`, at most 32 segments and 512 characters. Timestamps use UTC
+ISO format with milliseconds, as produced by the CLI.
+
+For noninteractive reset, pass both `--confirm=RESET` and `--yes`; `--json`
+returns `{reset: true, removedFiles: number}`. No password is required. Reset
+removes only `password.json`, `phrases.json`, `active.json`, `address-books.json`,
+`contacts.json`, `networks.json`, `session.json`, and `.machine-id`. It preserves
+the directory and unrelated files, and refuses to recurse into a directory
+occupying one of those filenames.
+
 ## Output And Automation
 
 Most commands print readable text by default. Commands intended for automation, such as `send`, also support JSON output: