@bwalletx/connect 0.5.6 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.7.0 (unreleased)
+
+**Use Metanet Desktop or another BRC-100 wallet** (owner, 6 Nov 2026: "ship a new one now with the metanet option"), with the rules of the live bChatX door (bit-sign 73f7d644).
+
+- **An explicit, visible choice.** "Use Metanet Desktop or another BRC-100 wallet · Metanet Desktop must be running on this computer": a link under `<bwalletx-signin>` (lg/md; `metanet="auto|on|off"`, React `metanet`), the chooser row that replaces "Desktop wallet", `useBwalletX().connectMetanet()` / `connect({ metanet: true })`, `runConnect({ metanet: true })`, `metanetOption()`. Pinned to `WalletClient('json-api')` on localhost:3321, never `'auto'`; it calls :3321 only after its own tap (getVersion first, so "nothing there" says "We couldn’t reach Metanet Desktop. Open it, then try again.").
+- **bWalletX stays the default.** The button's discovery never picks Metanet, even when it is the remembered wallet (`matchRemembered` → null); a remembered Metanet shows no "Continue with your wallet" or Switch note (`tapGoesElsewhere`).
+- **Remembered:** the type (`bwx:wallet = { type: 'metanet', substrate: 'json-api' }`) and the identity keys known on this origin (`bwx:known-keys`, public keys, newest 8; `knownIdentityKeys`, `isKnownIdentityKey`, `rememberKnownIdentityKey`). Every successful connect or sign-in adds its key.
+- **Return visit:** `planAutoConnect` → `'silent-metanet'`; ONE silent attempt per page load, 2 s (`trySilentMetanet`, `runSilentMetanet`), only for a key already known here; a locked, slow, absent or unknown wallet stops silently (no banner, no retry, no unlock prompt). With a session it attaches only the session's key. The element and the provider both run it.
+- **"Not you? Use another wallet"** under the button while Metanet is remembered (element `notYou()`, event `bwalletx-not-you`, `useBwalletX().forgetWallet()`), and Disconnect, forget the choice; a sign-in dropped mid-way lands nobody.
+- **Computers only**, never in a frame (`metanetOffered()`, `inAnyFrame()`); the chooser row is hidden there too.
+- **The minimum asked:** getVersion, isAuthenticated, the identity key, then the site's own call (the sign-in signature), one at a time; no protocol permission requests at connect.
+- **No coins:** a `createAction` that fails for lack of funds throws `PaymentError` `INSUFFICIENT_FUNDS` (`maybeSent: false`) with "Your wallet doesn't have enough to cover this payment and its small network fee. Add a little and try again." (`NO_COINS_TEXT`, `isInsufficientFunds`).
+- **Security review fixes:** no desktop wallet on localhost (Metanet on 3321, Cicada on 3301, `probeLocal`, a remembered 0.6.0 "Desktop wallet") is ever picked without its own tap: `autoChoice` and `matchRemembered` skip them (`isLocalDesktop`, `isLocalDesktopType`); a remembered `desktop` now plans `'none'`. Identity keys count as known only after a verified sign-in or a session match. `logoutUrl` / `logout-url` is required with `verifyUrl` (dev `console.warn`, `warnIfNoLogout`).
+- `isTouchDevice` moved to its own module (still exported from the package root and `modal`).
+
+## 0.6.0 (unreleased)
+
+Auto-connect for returning visitors (RB, 5 Nov 2026: "go on auto-connect"), within the wallet-choice rules of 0.5.6.
+
+- **The remembered choice.** After a sign-in the user explicitly picked (bWalletX's own button, a pick in the chooser, a site's `walletId`), the wallet TYPE is remembered for this origin: `localStorage['bwx:wallet'] = { type, substrate }`, e.g. `{ "type": "bwalletx", "substrate": "extension" }` or `{ "type": "io.yours", "substrate": "injected" }`. Never a key, address or handle; a bare `window.CWI` is never remembered (whoever holds it next time may be another wallet). `rememberWalletChoice`, `rememberedWalletChoice`, `forgetWalletChoice`.
+- **The next tap goes straight to it**, with no chooser, even when it isn't bWalletX (the user chose it). If it isn't here any more: bWalletX if here, else the chooser. A remembered desktop wallet probes localhost only after the tap.
+- **Nothing that could prompt fires on load.** `planAutoConnect()`: with a live server session and a remembered injected wallet, the provider picks the wallet up by discovery alone (`attachRemembered`: no wallet call, no localhost, no relay), so `pay`/`tip` work after a reload without another tap. Without a session, a connect would ask the wallet for a key or a signature, so it waits for the tap.
+- **"Some features need bWalletX · Switch"** under `<bwalletx-signin>` (lg/md; `switch-note="on|off"`) when the remembered wallet isn't bWalletX, and "Switch to bWalletX" in the signed-in menu. `switchToBwalletX()` on the element and in `useBwalletX()`; the `bwalletx-signin` event carries `mode: 'bwalletx'`. `useBwalletX()` adds `rememberedWallet` and `needsBwalletX`.
+- **Disconnect forgets** the remembered wallet (the provider's `disconnect()` and the element's menu).
+- Options: `BwalletXProvider rememberChoice` and `autoConnect` (both default true; both off with `fastPath={false}`), `runConnect({ remembered, remember, preferBwalletX })`, `decideWallet({ remembered, preferBwalletX })`, `<bwalletx-signin remember="off">`.
+- `<bwalletx-button>` shares the record: a 0.5.5 `bwx:connected` entry (which held the identity key) becomes `{ type: 'bwalletx' }` on load and the key is deleted (`migrateConnectedKey`); a tap on Connect remembers the type; Disconnect forgets it. Still zero wallet calls on load.
+- The one-sheet sign-in is unchanged: the identity key and the signature still go to the wallet together.
+
 ## 0.5.6 (unreleased)
 
 Wallet choice (RB, 5 Nov 2026: bWalletX is the default on our sites; no other wallet may take the sign-in flow). A fix: sites showed their own chooser even when only bWalletX was present, so users never saw the wallet sheet, and a wallet that held `window.CWI` was treated as bWalletX.

package/README.md

@@ -129,7 +129,7 @@ const r = await pay(wallet, { to: identityKeyHex, sats: 100 });            // BR
 await buyToken(wallet, { token: '$BOASE', amount: 100, quote: (q) => fetch('/api/quote', { method: 'POST', body: JSON.stringify(q) }).then((x) => x.json()) });
 ```
 
-Each call makes one `createAction`, and nothing is ever retried. Failures throw a `PaymentError` with a `code` (`BAD_REQUEST`, `RESOLVE_FAILED`, `RATE_FAILED`, `WALLET_REJECTED`, `WALLET_ERROR`, `NOT_SUPPORTED`). When `maybeSent` is true, the wallet may already have broadcast the payment, so check before you ask the user again. Browsers often can't resolve paymails themselves because of CORS, so pass `resolvePaymail` to do it on your server.
+Each call makes one `createAction`, and nothing is ever retried. Failures throw a `PaymentError` with a `code` (`BAD_REQUEST`, `RESOLVE_FAILED`, `RATE_FAILED`, `WALLET_REJECTED`, `WALLET_ERROR`, `NOT_SUPPORTED`, `INSUFFICIENT_FUNDS`). A wallet with no coins for the fee (0.7.0: the SDK's `WERR_INSUFFICIENT_FUNDS`, also over Metanet Desktop's JSON API, or a wallet's own "insufficient funds") gives `INSUFFICIENT_FUNDS` with `maybeSent: false` and one plain line you can show as is: "Your wallet doesn't have enough to cover this payment and its small network fee. Add a little and try again." (`NO_COINS_TEXT`; `isInsufficientFunds(e)` for your own calls). When `maybeSent` is true, the wallet may already have broadcast the payment, so check before you ask the user again. Browsers often can't resolve paymails themselves because of CORS, so pass `resolvePaymail` to do it on your server.
 
 **Verify payments on your server.** A txid or BEEF that comes back to the page is only what the page was told: a
 browser extension, a modified page or (before 0.5.2) a parent frame posing as the wallet can return a fake one.
@@ -167,7 +167,7 @@ bWalletX is the default on our sites, and no other wallet may take the sign-in f
 1. **bWalletX is recognised by its own announcement** (`com.bwalletx.extension`, `space.bwallet.mobile`) or by the bWalletX app frame, never by who holds `window.CWI`. Metanet / BSV Desktop or Yours can set or overwrite `window.CWI`; `discoverBwalletX()` no longer takes it.
 2. **bWalletX here → straight to its sheet.** No site chooser. A small **Other wallets** link under the button opens the chooser (phone QR, other browser wallets, desktop wallets).
 3. **No bWalletX → the chooser, "Get bWalletX" first**, then what was detected. Another wallet is connected only when the user picks it, even when it is the only one.
-4. **No localhost probe on load.** "Desktop wallet" in the chooser (`desktopOption()`) looks on localhost:3321 / 3301 only when tapped, so Chrome's Local Network Access prompt follows a tap.
+4. **No localhost probe on load.** "Use Metanet Desktop or another BRC-100 wallet" in the chooser (0.7.0; was "Desktop wallet") looks on localhost:3321 only when tapped, so Chrome's Local Network Access prompt follows a tap. `desktopOption()` (3321 / 3301) is still exported.
 
 `decideWallet(list, { chooser, picker, walletId, fastPath })` is the rule as a pure function; `runConnect`, `BwalletXProvider` and `<bwalletx-signin>` all use it. `chooseWallet(list)` is the chooser UI (`pickWallet` is the 0.5.5 one, still exported). If your site has its own chooser, call `decideWallet` first and show yours only when it answers `{ reason: 'chooser' }`:
 
@@ -181,6 +181,26 @@ const chosen = option ?? (reason === 'chooser' ? await chooseWallet(list) : null
 
 `BwalletXProvider fastPath={false}` (or `runConnect({ fastPath: false })`) restores the 0.5.5 picker rule. `connect({ chooser: true })` is the "Other wallets" link. `<bwalletx-signin other-wallets="auto|on|off">` controls the link (auto: shown at lg/md when the element signs in).
 
+### Returning visitors (0.6.0)
+
+After a sign-in the user explicitly picked, the wallet **type** is remembered for the origin (`localStorage['bwx:wallet']`, e.g. `{ "type": "io.yours", "substrate": "injected" }`; never a key). The next tap goes straight to that wallet, with no chooser. On load nothing that could prompt fires: with a live session the provider picks the remembered wallet up by discovery alone, so `pay`/`tip` work after a reload; without one, the next tap connects. If the remembered wallet isn't bWalletX, the element shows **Some features need bWalletX · Switch** (and "Switch to bWalletX" in its menu); `useBwalletX()` exposes `needsBwalletX` and `switchToBwalletX()` for your own UI. Disconnect forgets the choice. Turn it off with `rememberChoice={false}` / `autoConnect={false}` on the provider or `remember="off"` on the element.
+
+### Metanet Desktop and other BRC-100 wallets (0.7.0)
+
+**Use Metanet Desktop or another BRC-100 wallet** · *Metanet Desktop must be running on this computer.* A small link under `<bwalletx-signin>` (lg/md; `metanet="auto|on|off"`), a row in the chooser, `useBwalletX().connectMetanet()` or `runConnect({ metanet: true })`. The same rules as the bChatX door:
+
+1. **bWalletX stays the default.** It is found by its own announcement only; the button's discovery never picks Metanet, remembered or not. No desktop wallet on localhost is picked without its own tap: not by `autoChoice` / `fastPath={false}`, not after `probeLocal`, and not from a remembered 0.6.0 "Desktop wallet" (`isLocalDesktop`).
+2. **Pinned, and only on its own tap.** `WalletClient('json-api')` on localhost:3321, never `'auto'` (which would let the bWalletX extension or `window.CWI` answer). A first visit makes no :3321 call on page load.
+3. **Remembered:** the wallet type (`bwx:wallet = { "type": "metanet", "substrate": "json-api" }`) and the identity keys known on this origin (`bwx:known-keys`, public keys only). A key counts as known only after your verify route accepted its sign-in (or it matches the server session); a plain connect adds nothing.
+4. **Back with Metanet remembered:** one silent attempt per page load, a 2 s window (`trySilentMetanet` / `runSilentMetanet`). It goes on only if Metanet returns an identity key already known here, since whatever answers on :3321 might be another profile or another local process. Otherwise the normal choice, with no error banner and no retry. With a server session, it only attaches the wallet when it holds the session's key.
+5. **"Not you? Use another wallet"** (shown while Metanet is remembered) and Disconnect forget the choice; `useBwalletX().forgetWallet()` for your own UI. A sign-in dropped this way lands nobody (`logoutUrl` ends a session its verify already set).
+6. **Computers only**, never inside a frame (`metanetOffered()`).
+7. **The minimum:** `getVersion`, `isAuthenticated` (never prompts), the identity key, then the sign-in signature, one request at a time. No protocol permission requests at connect.
+
+Nothing on :3321 after a tap shows "We couldn’t reach Metanet Desktop. Open it, then try again."
+
+**`logoutUrl` / `logout-url` is required whenever `verifyUrl` / `verify-url` is set.** "Not you? Use another wallet" and Disconnect end the session the verify route created by POSTing to it; without it a silent Metanet sign-in the person rejected would stay signed in. In development the provider and the element `console.warn` once when it is missing.
+
 **Telemetry.** `onAttempt` (provider prop, `runConnect` option) and the element's `bwalletx-attempt` event report one record per attempt: `{ walletType, substrate, outcome, ms }`. `walletType` is `'bwalletx'` or the other wallet's rdns / option id; `substrate` is how it reached the page (`extension`, `in-app`, `xdm`, `injected`, `window.CWI`, `json-api`, `cicada`, `pairing`, `adapter`); `outcome` is `signed-in`, `connected`, `cancelled`, `rejected`, `not-found` or `error`. No keys, addresses or identity data.
 
 ## Migrating from HandCash Connect