@bwalletx/connect 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 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.
+
+- **bWalletX is recognised by its own announcement only.** `discoverBwalletX()` / `findBwalletX()` / `connectBwalletX()` no longer take `window.CWI` as bWalletX "in-app": Metanet / BSV Desktop or Yours can set or overwrite it. bWalletX is the BRC-100 announcement with rdns `com.bwalletx.extension` (extension) or `space.bwallet.mobile` (in-app browser; every build since 3 Oct 2026 announces), or the bWalletX app frame over XDM. A bare `window.CWI` is listed by `discoverWallets()` as "Browser wallet" (`substrate: 'window.CWI'`) and is never bWalletX.
+- **Fast path, on by default.** `decideWallet()` (new, pure) is the rule in `runConnect`, `BwalletXProvider.connect()` and `<bwalletx-signin>`: bWalletX here → straight to its sheet, no chooser, even with other wallets installed. Without it → the chooser, **Get bWalletX** first, then the detected wallets; another wallet is never connected unless picked (0.5.5 connected a lone Yours/Metanet with no picker). `picker: false` now means bWalletX, else the phone, else `NOT_FOUND`. `fastPath: false` restores the 0.5.5 rule.
+- **"Other wallets"**: a small link under `<bwalletx-signin>` (lg/md by default; `other-wallets="on|off"`) and in its not-found row; `connect({ chooser: true })` in the provider; the element's `bwalletx-signin` event carries `mode: 'chooser'`.
+- **`chooseWallet(list)`**: the new chooser (Get bWalletX first when absent; bWalletX the gold row when present; phone QR; other wallets tagged "Fewer features"; Desktop wallet; HandCash last; Esc / Cancel / backdrop close it). `pickWallet` is unchanged.
+- **No localhost probe before a tap.** `desktopOption()` ("Desktop wallet") probes localhost:3321 / 3301 only when its `connect()` runs, after the user picked it. `probeLocal` stays off by default.
+- **Telemetry hook**: `onAttempt` (provider prop / `runConnect` option) and the `bwalletx-attempt` event: `{ walletType, substrate, outcome, ms }` per attempt, nothing else.
+- `WalletOption.substrate`, `walletTypeOf`, `substrateOf`, `isPresentBwalletX`, `hasBwalletX`, `otherDetected`; `discoverWallets` also finds bWalletX in its app frame (XDM). `useBwalletX().walletType`.
+- Element: picking another wallet shows "Approve in your wallet…"; closing the phone QR returns to the button without an error.
+- **`<bwalletx-button>`: no wallet calls on load.** It used to call `getPublicKey` on load when `bwx:connected` was set, and stored the identity key there. Now it does discovery only; `bwx:connected` is deleted on load (`dropLegacyConnectedKey`) and never written; a reload shows Connect, and one tap reconnects. New `session-url` shows the chip from your server's session with no wallet call.
+
+## 0.5.5 (unreleased)
+
+- **One wallet sheet to sign in** (owner escalation, 2 Nov 2026: "FIVE PROMPTS??? FOR ONE CONNECTION?" on vexvoid.com). Measured with bWalletX 5.2.48: 0.5.4 asked for a picker plus 3 sheets on localhost, and a picker plus 5 sheets on the live site. Now:
+  - `signInWithBwalletX` gets the challenge first, with no key, then sends `getPublicKey({ identityKey: true })` and `createSignature` together (`Promise.all`), so the wallet can show one sheet. `identityKey` reuses a key you already have (the signature alone).
+  - `BwalletXProvider.connect()` (and `useBwalletX().connect()`) no longer asks for the key before signing in: the old path asked for it twice (once to connect, once to sign in). Logic in `runConnect()`.
+  - **Repeat sign-in is the signature alone**: the key that signed in last is remembered on the site (`rememberedIdentity()`, public data, a hint only). If another account is active, verification fails once and the sign-in is retried with the key asked for (`signInAndVerify`).
+  - `waitForAuthentication` is only called when the wallet says it is locked (`waitIfLocked`): bWalletX answers every call by fetching the site's manifest.json and, when that asks for permissions, showing a separate sheet each time.
+  - **Picker**: bWalletX is listed once (`window.CWI` is the same extension it announced; `cwiIsAnnounced`). With one wallet in the browser there is no picker at all (`autoChoice`); phone pairing is then a fallback, not a choice.
+  - **Server**: `createChallenge({ identityKey })` makes the key optional; a keyless challenge binds the key the browser claims at `verifySignIn`, and the signature only verifies for that key. A challenge made with a key still only verifies for that key. **Upgrade the server too** for one sheet: against a 0.5.4 server the browser falls back to the old order by itself (two sheets), or set `challengeNeedsIdentityKey`.
+- **The official element is stateful.** `<bwalletx-signin>` / `<BwalletxSignin>`: signed out → pending ("Approve in bWalletX…" with one line, "Sign in: shares only your public identity key, moves no money"; a body-level tip on `sm`/`icon`) → signed in (a badge: bAvatar, $handle from the paymail lookup or a short key, gold dot) with a menu (Copy paymail/key, Disconnect) → or an error line plus Retry ("Sign-in cancelled" for a no). The menu is a fixed, body-level portal (never clipped by `overflow:hidden`), keyboard operable, and fits a phone. Inside `<BwalletXProvider>` the element follows the provider (click → `connect()`, Disconnect → `disconnect()` → `logoutUrl`, reload restores from `sessionUrl` with no wallet prompt). Standalone: `session-url`, `logout-url`, `lookup-url`; `stateless` keeps the old plain button.
+- **`useBwalletXAccount()`**: `{ status, identityKey, paymail, handle, label, avatarUrl, error, login, logout }` for sites with their own UI.
+- **`<bwalletx-button>`: the one nav wallet control.** It renders Get bWalletX (deep-linked by platform), Connect bWalletX, or the $handle chip, by state, with the official button look. It guards against duplicates: a second instance and legacy controls in the same header/nav are hidden, with a console warning. Use only this element; don't add your own Get or Connect links.
+- **`<bwalletx-signin label="get">` and `label="play"`**: "Get bWalletX" and "Play with bWalletX", the same official button for download and play-now calls to action (with `href` link mode). First users: terrornode.com and tokenblaster.lol.
+
 ## 0.5.4 (unreleased)
 
 - **Connect is fast.** A wallet that is present now resolves at once: the extension answers `brc100:requestWallet` synchronously, and `window.CWI` (in-app browser) is taken straight away instead of after the wait. The wait for "nothing here" before the pairing QR drops from 1200 ms to 300 ms (`DEFAULT_DISCOVER_MS`); in a bWalletX frame the XDM probe now starts in parallel. `discoverWallets` stops waiting 50 ms after a wallet has announced. Measured in Chrome: pairing modal 1.24–1.34 s → 0.33–0.34 s after the click.

package/README.md

@@ -62,6 +62,10 @@ The cookie (`bwx_session`) is `HttpOnly; SameSite=Lax; Secure` (Secure when the
 
 Create the nonce table once (a migration): `pgNonceTableSql()` returns the SQL.
 
+**Hydration warning.** bWalletX for Chrome adds a `data-bwalletx-ext` attribute to `<html>` and `<body>` before React hydrates, so Next.js logs a harmless hydration mismatch. Put `suppressHydrationWarning` on both in `app/layout.tsx`: `<html lang="en" suppressHydrationWarning>` and `<body suppressHydrationWarning>`. It only silences attribute differences on those two elements, not in your components.
+
+**One sheet needs the server too.** The client and the challenge route must both be 0.5.5 or newer: an older `createChallenge` refuses a challenge without an identity key, and the client then falls back to asking for the key first (two wallet sheets).
+
 ## React quick start
 
 ```tsx
@@ -95,7 +99,22 @@ function Account() {
 
 `useBwalletX()` gives `status` (`idle | restoring | connecting | connected | error`), `identityKey`, `handle`, `paymail`, `wallet` (the BRC-100 `WalletInterface`), `walletId`, `signedIn`, `error`, `wallets`, `connect({ walletId? })`, `disconnect()`, `listWallets()`, `pay`, `tip` and `buyToken`.
 
-`connect()` finds wallets, shows the built-in picker when there is more than one (bWalletX first), shows the pairing QR modal for phones, and signs in through your routes when `challengeUrl` and `verifyUrl` are set. Nothing touches `window` during render, so the provider is safe in server-rendered pages. After a reload the session comes back from `sessionUrl`, but `wallet` stays `null` until the user calls `connect()` again.
+`connect()` finds wallets and signs in through your routes when `challengeUrl` and `verifyUrl` are set, with **one wallet sheet**: the challenge comes first (no key), then the identity key and the signature are asked for together, and a repeat sign-in on the same site is the signature alone. With bWalletX in the browser there is no chooser at all (0.5.6); without it the chooser opens with "Get bWalletX" first, and another wallet is used only when picked (see "Which wallet signs in"). Nothing touches `window` during render, so the provider is safe in server-rendered pages. After a reload the session comes back from `sessionUrl`, but `wallet` stays `null` until the user calls `connect()` again.
+
+### Drop-in: provider + one element + 3 routes
+
+The official element follows the provider, so one element gives the whole experience: **Sign in with bWalletX** → **Approve in bWalletX…** (with one line: "Sign in: shares only your public identity key, moves no money") → a signed-in badge (bAvatar, $handle or a short key, gold dot) whose menu has **Copy paymail/key** and **Disconnect**. A reload restores the badge from `sessionUrl` with no wallet prompt. A no in the wallet reads "Sign-in cancelled" with **Retry**.
+
+```tsx
+<BwalletXProvider challengeUrl="/api/bwalletx/challenge" verifyUrl="/api/bwalletx/verify"
+  logoutUrl="/api/bwalletx/logout" sessionUrl="/api/bwalletx/session">
+  <BwalletxSignin size="sm" />   {/* in your header; that's all */}
+</BwalletXProvider>
+```
+
+Your own UI instead: `const { status, identityKey, paymail, handle, label, avatarUrl, error, login, logout } = useBwalletXAccount();` (`status`: `restoring | signed-out | pending | signed-in | error`).
+
+**Upgrade the server too.** The one-sheet order needs a challenge route that accepts no key: `createChallenge` / `createBwalletXAuth` from 0.5.5. Against an older server the browser sees the refusal and falls back to the old order (two sheets) by itself; `challengeNeedsIdentityKey` skips the attempt.
 
 ## Payments
 
@@ -133,12 +152,36 @@ Every expected output has to be matched by a different output that carries at le
 `discoverWallets()` lists everything it can find, with bWalletX first:
 
 - every wallet that announces itself through BRC-100 discovery (bWalletX, Yours, Metanet and others)
-- the in-app browser's `window.CWI`
-- desktop wallets on localhost ports 3321 and 3301 (only with `probeLocal: true`)
+- bWalletX in its own app frame (XDM, only from bWalletX's origins)
+- a `window.CWI` that nobody announced, under a neutral name ("Browser wallet"); it is never taken for bWalletX
+- desktop wallets on localhost ports 3321 and 3301 (only with `probeLocal: true`; prefer `desktopOption()`, below)
 - phone pairing (`pairing: pairingModal()`)
 - any adapters you add in `extra`
 
-`pickWallet(list)` shows the picker. `pairingModal()` returns `PairingOptions` that draw the QR code and match code, so you no longer need your own QR library. On phones and tablets it shows an **Open bWalletX** button (the pairing universal link opens the app) and a web.bwalletx.com fallback instead of a QR; pass `mode: 'qr'` or `'app'` to force one.
+`pairingModal()` returns `PairingOptions` that draw the QR code and match code, so you no longer need your own QR library. On phones and tablets it shows an **Open bWalletX** button (the pairing universal link opens the app) and a web.bwalletx.com fallback instead of a QR; pass `mode: 'qr'` or `'app'` to force one.
+
+### Which wallet signs in (0.5.6)
+
+bWalletX is the default on our sites, and no other wallet may take the sign-in flow:
+
+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.
+
+`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' }`:
+
+```ts
+import { discoverWallets, decideWallet, chooseWallet, pairingModal } from '@bwalletx/connect';
+
+const list = await discoverWallets({ pairing: () => pairingModal() });
+const { option, reason } = decideWallet(list);            // bWalletX here → option, no chooser
+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).
+
+**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
 
@@ -156,6 +199,25 @@ Every expected output has to be matched by a different output that carries at le
 3. Replace HandCash payment calls with `pay` / `tip` / `buyToken`, and check them on the server with `verifyPayment` instead of HandCash payment webhooks.
 4. Remove the adapter when your users have moved over.
 
+## The nav wallet control: use only `<bwalletx-button>`
+
+**Use only this element for your site's wallet control. Don't add your own "Get bWalletX" or "Connect" links or buttons next to it.** It renders exactly one thing by state:
+
+| State | Shows |
+|---|---|
+| No wallet in this browser | **Get bWalletX** (a link: bwalletx.com/extension on desktop Chrome, /iphone, /android, else /get) |
+| A wallet here, not connected | **Connect bWalletX** (extension, in-app browser, or a QR to the phone app) |
+| Connected | The **$handle chip** (click to disconnect) |
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@bwalletx/connect/dist/bwalletx-connect.global.js"></script>
+<header>… <bwalletx-button></bwalletx-button></header>
+```
+
+Or `import '@bwalletx/connect/element'`. Attributes: `size` (sm, md, lg), `get-url`, `discover-ms`, `lookup-url`. Events: `bwalletx-connected` `{ identityKey }` and `bwalletx-disconnected`.
+
+**Guard:** there is one per page. A second `<bwalletx-button>` hides itself. Legacy controls inside the same `<header>`/`<nav>` (`[data-bwx-connect]`, `.nav-connect`, `.nav-acct`, links to bwalletx.com/get) are hidden too. Each one hidden logs a console warning. Links in your page content are left alone.
+
 ## The button
 
 `<bwalletx-signin>` is the standard "Sign in with bWalletX" button: a web component with no dependencies (Shadow DOM), plus a React wrapper. It is the gold button from bit-sign's sign-in card.
@@ -184,12 +246,18 @@ import { BwalletxSignin } from '@bwalletx/connect/react';
 | `brand` | `bWalletX` (default), `bWallet` (store edition) |
 | `subtitle` | `on`, `off`, or your own text. Default "also works with bWallet" on lg/md |
 | `full-width`, `loading`, `disabled` | flags |
-| `challenge-url`, `verify-url` | run the sign-in flow on click: POST `{ identityKey }`, then POST `{ identityKey, nonce, signature }` |
+| `challenge-url`, `verify-url` | run the sign-in flow on click: POST `{}` (one sheet; `{ identityKey }` on a repeat sign-in), then POST `{ identityKey, nonce, signature }` |
+| `session-url`, `logout-url` | restore the signed-in badge on load (no wallet prompt); POST on Disconnect |
+| `lookup-url` | paymail lookup for the badge (default pay.bwallet.space; `off`) |
+| `stateless` | the pre-0.5.5 plain button: no badge, no pending/error states |
+| `state` (+ `identity-key`, `paymail`, `handle`, `avatar-url`, `error`) | drive the states yourself; `<BwalletxSignin>` inside `<BwalletXProvider>` does this for you |
 | `get-url`, `web-url` | where "Get bWalletX" and the web wallet link go (bwalletx.com/get, web.bwalletx.com) |
 | `href` | navigate on click instead |
 | `authorize-url`, `client-id`, `redirect-uri`, `scope` | OAuth 2.1 redirect with S256 PKCE (verifier, state and nonce in `sessionStorage["bwalletx:oauth"]`). For auth.bwalletx.com, which is planned and not live yet |
 
-Events (bubbling, composed): `bwalletx-signin` on every click (call `preventDefault()` to run your own flow instead), `bwalletx-signed-in` with `{ identityKey, method, nonce, signature, response }`, `bwalletx-not-found` (the button then shows "Get bWalletX" and a web wallet link), `bwalletx-error` with `{ error }`.
+Events (bubbling, composed): `bwalletx-signin` on every click (call `preventDefault()` to run your own flow instead), `bwalletx-signed-in` with `{ identityKey, method, nonce, signature, response }`, `bwalletx-not-found` (the button then shows "Get bWalletX" and a web wallet link), `bwalletx-error` with `{ error }`, `bwalletx-disconnect` (cancelable; Disconnect in the badge menu) and `bwalletx-signed-out`.
+
+States: signed out → pending ("Approve in bWalletX…" plus one plain line) → signed in (the badge; its menu is a body-level portal, so an `overflow:hidden` header never clips it, and it is keyboard operable: Enter/↓ opens, arrows move, Esc closes) or error (one line plus Retry).
 
 Without `challenge-url`, `href` or `authorize-url` the button only fires `bwalletx-signin`. The built-in flow uses the extension or in-app browser only. For phone pairing, listen for `bwalletx-signin`, call `preventDefault()`, and call `signInWithBwalletX` with `pairing` as shown above.
 
@@ -203,7 +271,7 @@ import { createChallenge, verifySignIn, originAllowed, memoryStore } from '@bwal
 const ORIGIN = 'https://example.com'; // your site, from config. Never from the request.
 const store = memoryStore();          // dev only. See "Nonce store" below.
 
-// POST /auth/bwalletx/challenge   body: { identityKey }
+// POST /auth/bwalletx/challenge   body: {} (or { identityKey })
 app.post('/auth/bwalletx/challenge', async (req, res) => {
   if (!originAllowed(req.get('origin'), ORIGIN)) return res.status(403).end();
   try {
@@ -223,7 +291,7 @@ app.post('/auth/bwalletx/verify', async (req, res) => {
 });
 ```
 
-`verifySignIn` returns the identity key (66 lowercase hex characters) or `null`. It refuses a nonce that was already used, has expired (2 minutes), was issued for another origin or another identity key, or whose signature doesn't verify.
+`verifySignIn` returns the identity key (66 lowercase hex characters) or `null`. It refuses a nonce that was already used, has expired (2 minutes), was issued for another origin or another identity key, or whose signature doesn't verify. Since 0.5.5 `identityKey` is optional in `createChallenge`: a challenge made without one binds the key the browser claims at verify, and the signature only verifies for that key. That lets the browser ask the wallet for the key and the signature in one sheet.
 
 The text the wallet signs: