@bwalletx/connect 0.5.4 → 0.5.6

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 import { WalletInterface, WalletProtocol } from '@bsv/sdk';
-import { f as PairingOptions, W as WalletOption } from './wallets-CbzMtxrf.cjs';
-export { g as BRC29_PROTOCOL, i as Brc29Remittance, B as BuyTokenRequest, C as ConnectedWallet, D as DiscoverWalletsOptions, H as HandCashAdapterOptions, L as LegacyPayer, j as PairConnectionOptions, k as PairStorage, l as PairedWallet, b as PayOptions, m as PayOutput, P as PayRequest, a as PayResult, n as PaySource, c as PaymentError, o as PaymentErrorCode, S as SocketFactory, q as SocketLike, T as TokenQuote, r as WalletKind, s as amountInSats, d as brc100Option, t as buyToken, u as clearPairing, e as discoverWallets, h as handcashAdapter, v as isIdentityKeyHex, w as isPaymail, x as pairBwalletX, p as pairingOption, y as pay, z as resolvePaymailP2P, A as restorePairing, E as tip } from './wallets-CbzMtxrf.cjs';
-export { AuthorizeParams, GET_URL, SIGNIN_CSS, SIGNIN_TAG, SigninBrand, SigninLabel, SigninSize, SigninTheme, WEB_WALLET_URL, buildAuthorizeUrl, defineBwalletxSignin, markSvg, signinText } from './element.cjs';
+import { g as PairingOptions, W as WalletOption, A as AttemptHook, C as ConnectedWallet, S as Substrate, i as ChoiceReason } from './choice-DCh-tgpT.cjs';
+export { j as AttemptOutcome, k as BRC29_PROTOCOL, l as BWALLETX_TYPE, m as Brc29Remittance, B as BuyTokenRequest, n as ConnectAttempt, o as ConnectOptions, D as DESKTOP_OPTION_ID, q as DecideWalletOptions, r as DiscoverWalletsOptions, H as HandCashAdapterOptions, L as LegacyPayer, s as PairConnectionOptions, t as PairStorage, u as PairedWallet, b as PayOptions, v as PayOutput, P as PayRequest, a as PayResult, w as PaySource, c as PaymentError, x as PaymentErrorCode, y as SocketFactory, z as SocketLike, T as TokenQuote, E as WalletChoice, F as WalletKind, G as amountInSats, I as attemptFor, d as autoChoice, e as brc100Option, J as buyToken, K as chooserOrder, M as clearPairing, N as cwiIsAnnounced, O as decideWallet, Q as desktopOption, f as discoverWallets, h as handcashAdapter, R as hasBwalletX, U as isIdentityKeyHex, V as isPaymail, X as isPresentBwalletX, Y as otherDetected, Z as outcomeOf, _ as pairBwalletX, p as pairingOption, $ as pay, a0 as reportAttempt, a1 as resolvePaymailP2P, a2 as restorePairing, a3 as substrateOf, a4 as tip, a5 as walletTypeOf } from './choice-DCh-tgpT.cjs';
+export { A as AuthorizeParams, G as GET_URL, M as MENU_CSS, P as PENDING_LABEL, e as PENDING_LABEL_OTHER, f as PENDING_NOTE, g as SIGNIN_CSS, h as SIGNIN_TAG, i as SigninAccount, c as SigninBrand, b as SigninLabel, j as SigninMode, S as SigninSize, d as SigninState, a as SigninTheme, W as WEB_WALLET_URL, k as buildAuthorizeUrl, l as defineBwalletxSignin, m as markSvg, s as signinText } from './element-D9Zl-x12.cjs';
+export { BUTTON_TAG, ButtonState, CONNECTED_KEY, defineBwalletxButton, dropLegacyConnectedKey, getUrlFor, handleLabel, stateFor } from './element.cjs';
 import { b as AccessResponse, H as HoldingProof, A as AccessError } from './access-Dp0eKIOc.cjs';
 export { f as ACCESS_ERROR_STATUS, d as ACCESS_PROTOCOL, g as ACCESS_VERSION, h as AccessChallenge, i as AccessErrorBody, j as AccessErrorCode, c as AccessKind, a as AccessRequirement, P as PROTOCOL_MEDIA, T as TokenRequirement, k as accessErrorMessage, m as canonicalJson, r as protocolMediaUrl } from './access-Dp0eKIOc.cjs';
 
@@ -17,16 +18,21 @@ interface FoundWallet {
     rdns: string | null;
 }
 /**
- * Default wait for a wallet that has not answered yet, ms. bWalletX for Chrome answers `brc100:requestWallet`
- * synchronously and the in-app browser sets `window.CWI` before the page runs, so a found wallet resolves at once;
+ * Default wait for a wallet that has not answered yet, ms. bWalletX for Chrome and the in-app browser both answer
+ * `brc100:requestWallet` synchronously, so a found wallet resolves at once;
  * this is only how long "nothing here" takes before the pairing QR shows. Was 1200 (0.5.3 and earlier).
  */
 declare const DEFAULT_DISCOVER_MS = 300;
 /**
  * Like findBwalletX, but also says which bWalletX answered.
- * Order: a BRC-100 announcement with a bWalletX rdns (answered at once by the extension); then `window.CWI` (set by
- * the in-app browser, and by older builds that do not announce), taken straight away; then, only when framed, the
- * parent's XDM answer (probed in parallel with the wait). Otherwise null after `ms`.
+ *
+ * bWalletX is recognised ONLY by its own markers: a BRC-100 announcement carrying a bWalletX rdns
+ * (`com.bwalletx.extension` from the Chrome extension, `space.bwallet.mobile` from the in-app browser; both answer
+ * `brc100:requestWallet` at once), or, only when framed, the XDM answer of a parent on BWALLETX_PARENT_ORIGINS.
+ *
+ * Never by `window.CWI` (0.5.6): another wallet (Metanet / BSV Desktop, Yours) can set or overwrite it, and treating
+ * whoever holds it as bWalletX handed our sign-in to that wallet. Every bWalletX build since 3 Oct 2026 announces.
+ * Resolves null after `ms` when no bWalletX announced (other wallets: discoverWallets).
  */
 declare function discoverBwalletX(ms?: number): Promise<FoundWallet | null>;
 /**
@@ -34,6 +40,8 @@ declare function discoverBwalletX(ms?: number): Promise<FoundWallet | null>;
  * open in bWalletX's in-app browser. Resolves null if nothing answered within `ms`.
  */
 declare function findBwalletX(ms?: number): Promise<WalletInterface | null>;
+/** True inside a frame (or when the parent can't be read). */
+declare const isFramed: () => boolean;
 /**
  * Wake the wallet before the click (call on pointerenter / focus / touchstart of your Connect button). Chrome stops an
  * idle extension worker after ~30 s, and a cold worker needs 1-3 s to reopen the wallet; this sends a liveness call
@@ -57,12 +65,32 @@ type SignInMethod = 'extension' | 'in-app' | 'pairing' | 'wallet';
 /**
  * Progress for the button label. 'finding': looking for a wallet (sub-second); 'opening': a wallet was found and its
  * approval is on the way ("Opening your wallet…"); 'pairing': no wallet in this browser, the QR is showing;
- * 'signing': the identity key arrived, the sign-in signature is being asked for.
+ * 'signing': the challenge arrived, the wallet's sign-in approval is being asked for.
  */
 type SignInStatus = 'finding' | 'opening' | 'pairing' | 'signing';
 interface SignInOptions {
-    /** Ask your server for a challenge for this identity key. */
-    challenge: (identityKey: string) => Promise<Challenge>;
+    /**
+     * Ask your server for a challenge. Since 0.5.5 it is called BEFORE the wallet is asked anything, and gets an identity
+     * key only when you pass `identityKey` (an identity you already connected) or set `challengeNeedsIdentityKey`;
+     * otherwise undefined. The 0.5.5 server helpers (createChallenge) accept no key, and verifySignIn binds the key the
+     * browser then claims to the signature. A pre-0.5.5 server that refuses a keyless challenge is detected and retried
+     * in the old order automatically.
+     */
+    challenge(identityKey?: string): Promise<Challenge>;
+    /**
+     * The identity key you already have from an earlier connect (reuse the connected identity): the wallet is then asked
+     * for the signature only. Without it, getPublicKey({ identityKey: true }) and createSignature go to the wallet
+     * together (Promise.all), so the wallet shows ONE sheet, not three.
+     */
+    identityKey?: string;
+    /**
+     * Servers older than 0.5.5 refuse a challenge without an identity key. Set true to use the old order straight away
+     * (identity key, then the challenge, then the signature: two wallet calls). Without it, the old order is used only
+     * after such a server has refused a keyless challenge.
+     */
+    challengeNeedsIdentityKey?: boolean;
+    /** Skip waitForAuthentication before signing (the provider already waited). Default false. */
+    skipWaitForAuthentication?: boolean;
     /** Use this wallet instead of looking for one. `method` is then 'wallet'. */
     wallet?: WalletInterface;
     /** How to show the QR and code if pairing is needed. Without it, pairing is not tried. */
@@ -89,10 +117,41 @@ declare function connectBwalletX(opts?: Pick<SignInOptions, 'wallet' | 'pairing'
     method: SignInMethod;
 }>;
 /**
- * Sign the server's challenge with the user's bWalletX identity key. Post the result's
- * identityKey, nonce and signature to your verify route.
+ * Wait for the user to unlock only when the wallet says it is locked. isAuthenticated never shows anything; an
+ * unconditional waitForAuthentication is not free: bWalletX answers it by fetching the site's manifest.json and, when
+ * that asks for permissions, shows a separate sheet, once per call.
+ */
+declare function waitIfLocked(wallet: WalletInterface): Promise<void>;
+/**
+ * True when a server refused a challenge because it wanted an identity key (createChallenge before 0.5.5 answers 400
+ * "identityKey must be a compressed public key (66 hex chars)").
+ */
+declare function challengeWantsIdentityKey(e: unknown): boolean;
+/**
+ * Sign the server's challenge with the user's bWalletX identity key. Post the result's identityKey, nonce and
+ * signature to your verify route.
+ *
+ * Wallet calls, in order:
+ *   1. the challenge comes from your server first (no wallet call);
+ *   2. getPublicKey({ identityKey: true }) and createSignature go to the wallet TOGETHER, so the wallet merges them
+ *      into one approval. With `identityKey` (already connected) only createSignature is asked for.
  */
 declare function signInWithBwalletX(opts: SignInOptions): Promise<SignInResult>;
+interface SignInAndVerifyOptions extends SignInOptions {
+    /** POST the result to your verify route; resolve with its JSON. A 401 (status on the error) means "sign-in failed". */
+    verify: (r: SignInResult) => Promise<Record<string, unknown>>;
+    /**
+     * A remembered identity key (rememberedIdentity()). Used like `identityKey` (one wallet call: the signature only),
+     * but if the server rejects the signature (another account is active now), it is dropped and the sign-in is retried
+     * with the key asked for.
+     */
+    identityKeyHint?: string;
+}
+/** signInWithBwalletX + your verify route, with the identity-hint fallback. */
+declare function signInAndVerify(opts: SignInAndVerifyOptions): Promise<{
+    result: SignInResult;
+    verified: Record<string, unknown>;
+}>;
 /** Where a sign-in failed: the wallet's identity prompt, the site's challenge endpoint, or the wallet's signature. */
 type SignInStage = 'identity' | 'challenge' | 'signature' | 'verify';
 
@@ -115,6 +174,38 @@ declare function renderButton(el: HTMLElement | string, opts?: ButtonOptions): H
  */
 declare function inOrder<T>(handle: (frame: T) => Promise<void> | void, onError?: (e: unknown) => void): (frame: T) => Promise<void>;
 
+/**
+ * The signed-in account as the badge shows it: paymail (best-effort lookup by identity key), a $handle label, a short
+ * key when there is no paymail, and the bAvatar picture (gold by default, generated for any key).
+ */
+declare const PAYMAIL_LOOKUP_URL = "https://pay.bwallet.space/api/paymail/lookup?key=";
+declare const BAVATAR_URL = "https://chat.bwalletx.com/api/bavatar/";
+/** 0266c1…7c83 */
+declare function shortKey(key: string): string;
+/** $alice for alice@bwalletx.com, a site handle as given, other paymails in full, else a short key. */
+declare function accountLabel(a: {
+    identityKey?: string | null;
+    paymail?: string | null;
+    handle?: string | null;
+}): string;
+/** The bAvatar for an identity key (a generated gold avatar when the user has not set one). */
+declare function avatarUrlFor(identityKey: string | null | undefined): string | null;
+/** The paymail for an identity key, or null. Best effort: never throws, one request per key per page. */
+declare function lookupPaymail(identityKey: string, url?: string): Promise<string | null>;
+/** True when the user said no in the wallet (BRC-100 denial, or a picker / sheet closed). */
+declare function isUserRejection(e: unknown): boolean;
+/** One plain line for an error: "Sign-in cancelled" for a no in the wallet, otherwise the gist. */
+declare function signInErrorText(e: unknown): string;
+/** localStorage key for the identity key that last signed in on this site (public data; a hint, never trusted). */
+declare const IDENTITY_HINT_KEY = "bwx:identityKey";
+/**
+ * The identity key that last signed in on this site, if any. Passing it to signInWithBwalletX makes a repeat sign-in
+ * ONE wallet call (createSignature only). It is only a hint: the server still checks the signature against it, and a
+ * wrong hint (another account) fails verification and is retried with the key asked for.
+ */
+declare function rememberedIdentity(): string | undefined;
+declare function rememberIdentity(key: string | null): void;
+
 /** An SVG QR code for `text` (error correction M). */
 declare function qrSvg(text: string): string;
 /**
@@ -149,6 +240,24 @@ declare function pairingModal(o?: PairingModalOptions): PairingOptions & {
 declare function pickWallet(options: WalletOption[], o?: {
     title?: string;
 }): Promise<WalletOption | null>;
+interface ChooseWalletOptions {
+    /** Default "Choose a wallet". */
+    title?: string;
+    /** Where "Get bWalletX" points. Default https://bwalletx.com/get */
+    getUrl?: string;
+    /**
+     * Offer "Desktop wallet" (Metanet / BSV Desktop on localhost). Default true. It probes localhost only when tapped
+     * (desktopOption), never while the chooser opens.
+     */
+    desktop?: boolean;
+}
+/**
+ * The wallet chooser (0.5.6). Without bWalletX in this browser, "Get bWalletX" comes first; then bWalletX on the
+ * phone, the other wallets that were detected, "Desktop wallet" (probes localhost only when tapped) and app-supplied
+ * options. Opened from "Other wallets" while bWalletX is here, bWalletX is the first, gold row.
+ * Resolves with the chosen option, or null when closed. "Get bWalletX" is a link and leaves the chooser open.
+ */
+declare function chooseWallet(options: readonly WalletOption[], o?: ChooseWalletOptions): Promise<WalletOption | null>;
 
 /**
  * Browser side of the access protocol: ask the wallet to sign the site's challenge and prove the
@@ -201,4 +310,44 @@ declare const WALLET_THEME_META = "bwalletx-theme";
 /** Declare (or with null, withdraw) the theme the wallet should wear for this page. No-op outside a browser. */
 declare function declareWalletTheme(theme: string | null | undefined): void;
 
-export { type AccessChallengeLike, AccessError, AccessResponse, BWALLETX_RDNS, type ButtonOptions, type Challenge, DEFAULT_DISCOVER_MS, type FoundBy, type FoundWallet, HoldingProof, LOGIN_PROTOCOL, LOGO_URL, type PairingModalOptions, PairingOptions, RDNS_EXTENSION, RDNS_MOBILE, type RequestAccessOptions, type RequestAccessResult, type SignInMethod, type SignInOptions, type SignInResult, type SignInStage, type SignInStatus, WALLET_THEME_META, WalletOption, bindPrewarm, connectBwalletX, declareWalletTheme, discoverBwalletX, findBwalletX, inOrder, isTouchDevice, pairingModal, pickWallet, prewarmBwalletX, proveHoldings, qrSvg, renderButton, requestAccess, signInWithBwalletX, throwIfAccessError, toAccessError };
+interface ConnectFlowOptions {
+    /** The wallets found (discoverWallets). */
+    list: WalletOption[];
+    /** Connect this option without asking. */
+    walletId?: string;
+    /** false: never show the chooser (bWalletX, else the phone; never another wallet unasked). Default true. */
+    picker?: boolean;
+    /** "Other wallets": show the chooser even when bWalletX is here. */
+    chooser?: boolean;
+    /**
+     * bWalletX first (0.5.6, default true): bWalletX in this browser is connected with no chooser; without it the
+     * chooser opens ("Get bWalletX" first) and no other wallet is connected unless picked. false: the 0.5.5 rule.
+     */
+    fastPath?: boolean;
+    /** Show the chooser; resolves null when closed. chooseWallet (modal.ts) or your own UI. */
+    pick: (list: WalletOption[]) => Promise<WalletOption | null>;
+    /** With verifyUrl: sign in after connecting. */
+    challengeUrl?: string;
+    verifyUrl?: string;
+    challengeNeedsIdentityKey?: boolean;
+    /** POST JSON; throws with `status` on a non-2xx answer. */
+    post: (url: string, body: unknown) => Promise<Record<string, unknown>>;
+    /** Called once per attempt with { walletType, substrate, outcome, ms }. No keys, addresses or identity data. */
+    onAttempt?: AttemptHook;
+}
+interface ConnectFlowResult {
+    connected: ConnectedWallet;
+    identityKey: string | null;
+    handle: string | null;
+    paymail: string | null;
+    signedIn: boolean;
+    /** 'bwalletx' for bWalletX, else the wallet's rdns / option id. */
+    walletType: string;
+    substrate: Substrate;
+    /** Why this wallet: 'bwalletx' (fast path), 'chooser' (picked), 'requested' (walletId), … */
+    reason: ChoiceReason;
+}
+/** Resolves null when the user closed the chooser. Throws NOT_FOUND when there is nothing to connect. */
+declare function runConnect(o: ConnectFlowOptions): Promise<ConnectFlowResult | null>;
+
+export { type AccessChallengeLike, AccessError, AccessResponse, AttemptHook, BAVATAR_URL, BWALLETX_RDNS, type ButtonOptions, type Challenge, ChoiceReason, type ChooseWalletOptions, type ConnectFlowOptions, type ConnectFlowResult, ConnectedWallet, DEFAULT_DISCOVER_MS, type FoundBy, type FoundWallet, HoldingProof, IDENTITY_HINT_KEY, LOGIN_PROTOCOL, LOGO_URL, PAYMAIL_LOOKUP_URL, type PairingModalOptions, PairingOptions, RDNS_EXTENSION, RDNS_MOBILE, type RequestAccessOptions, type RequestAccessResult, type SignInAndVerifyOptions, type SignInMethod, type SignInOptions, type SignInResult, type SignInStage, type SignInStatus, Substrate, WALLET_THEME_META, WalletOption, accountLabel, avatarUrlFor, bindPrewarm, challengeWantsIdentityKey, chooseWallet, connectBwalletX, declareWalletTheme, discoverBwalletX, findBwalletX, inOrder, isFramed, isTouchDevice, isUserRejection, lookupPaymail, pairingModal, pickWallet, prewarmBwalletX, proveHoldings, qrSvg, rememberIdentity, rememberedIdentity, renderButton, requestAccess, runConnect, shortKey, signInAndVerify, signInErrorText, signInWithBwalletX, throwIfAccessError, toAccessError, waitIfLocked };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { WalletInterface, WalletProtocol } from '@bsv/sdk';
-import { f as PairingOptions, W as WalletOption } from './wallets-CbzMtxrf.js';
-export { g as BRC29_PROTOCOL, i as Brc29Remittance, B as BuyTokenRequest, C as ConnectedWallet, D as DiscoverWalletsOptions, H as HandCashAdapterOptions, L as LegacyPayer, j as PairConnectionOptions, k as PairStorage, l as PairedWallet, b as PayOptions, m as PayOutput, P as PayRequest, a as PayResult, n as PaySource, c as PaymentError, o as PaymentErrorCode, S as SocketFactory, q as SocketLike, T as TokenQuote, r as WalletKind, s as amountInSats, d as brc100Option, t as buyToken, u as clearPairing, e as discoverWallets, h as handcashAdapter, v as isIdentityKeyHex, w as isPaymail, x as pairBwalletX, p as pairingOption, y as pay, z as resolvePaymailP2P, A as restorePairing, E as tip } from './wallets-CbzMtxrf.js';
-export { AuthorizeParams, GET_URL, SIGNIN_CSS, SIGNIN_TAG, SigninBrand, SigninLabel, SigninSize, SigninTheme, WEB_WALLET_URL, buildAuthorizeUrl, defineBwalletxSignin, markSvg, signinText } from './element.js';
+import { g as PairingOptions, W as WalletOption, A as AttemptHook, C as ConnectedWallet, S as Substrate, i as ChoiceReason } from './choice-DCh-tgpT.js';
+export { j as AttemptOutcome, k as BRC29_PROTOCOL, l as BWALLETX_TYPE, m as Brc29Remittance, B as BuyTokenRequest, n as ConnectAttempt, o as ConnectOptions, D as DESKTOP_OPTION_ID, q as DecideWalletOptions, r as DiscoverWalletsOptions, H as HandCashAdapterOptions, L as LegacyPayer, s as PairConnectionOptions, t as PairStorage, u as PairedWallet, b as PayOptions, v as PayOutput, P as PayRequest, a as PayResult, w as PaySource, c as PaymentError, x as PaymentErrorCode, y as SocketFactory, z as SocketLike, T as TokenQuote, E as WalletChoice, F as WalletKind, G as amountInSats, I as attemptFor, d as autoChoice, e as brc100Option, J as buyToken, K as chooserOrder, M as clearPairing, N as cwiIsAnnounced, O as decideWallet, Q as desktopOption, f as discoverWallets, h as handcashAdapter, R as hasBwalletX, U as isIdentityKeyHex, V as isPaymail, X as isPresentBwalletX, Y as otherDetected, Z as outcomeOf, _ as pairBwalletX, p as pairingOption, $ as pay, a0 as reportAttempt, a1 as resolvePaymailP2P, a2 as restorePairing, a3 as substrateOf, a4 as tip, a5 as walletTypeOf } from './choice-DCh-tgpT.js';
+export { A as AuthorizeParams, G as GET_URL, M as MENU_CSS, P as PENDING_LABEL, e as PENDING_LABEL_OTHER, f as PENDING_NOTE, g as SIGNIN_CSS, h as SIGNIN_TAG, i as SigninAccount, c as SigninBrand, b as SigninLabel, j as SigninMode, S as SigninSize, d as SigninState, a as SigninTheme, W as WEB_WALLET_URL, k as buildAuthorizeUrl, l as defineBwalletxSignin, m as markSvg, s as signinText } from './element-D9Zl-x12.js';
+export { BUTTON_TAG, ButtonState, CONNECTED_KEY, defineBwalletxButton, dropLegacyConnectedKey, getUrlFor, handleLabel, stateFor } from './element.js';
 import { b as AccessResponse, H as HoldingProof, A as AccessError } from './access-Dp0eKIOc.js';
 export { f as ACCESS_ERROR_STATUS, d as ACCESS_PROTOCOL, g as ACCESS_VERSION, h as AccessChallenge, i as AccessErrorBody, j as AccessErrorCode, c as AccessKind, a as AccessRequirement, P as PROTOCOL_MEDIA, T as TokenRequirement, k as accessErrorMessage, m as canonicalJson, r as protocolMediaUrl } from './access-Dp0eKIOc.js';
 
@@ -17,16 +18,21 @@ interface FoundWallet {
     rdns: string | null;
 }
 /**
- * Default wait for a wallet that has not answered yet, ms. bWalletX for Chrome answers `brc100:requestWallet`
- * synchronously and the in-app browser sets `window.CWI` before the page runs, so a found wallet resolves at once;
+ * Default wait for a wallet that has not answered yet, ms. bWalletX for Chrome and the in-app browser both answer
+ * `brc100:requestWallet` synchronously, so a found wallet resolves at once;
  * this is only how long "nothing here" takes before the pairing QR shows. Was 1200 (0.5.3 and earlier).
  */
 declare const DEFAULT_DISCOVER_MS = 300;
 /**
  * Like findBwalletX, but also says which bWalletX answered.
- * Order: a BRC-100 announcement with a bWalletX rdns (answered at once by the extension); then `window.CWI` (set by
- * the in-app browser, and by older builds that do not announce), taken straight away; then, only when framed, the
- * parent's XDM answer (probed in parallel with the wait). Otherwise null after `ms`.
+ *
+ * bWalletX is recognised ONLY by its own markers: a BRC-100 announcement carrying a bWalletX rdns
+ * (`com.bwalletx.extension` from the Chrome extension, `space.bwallet.mobile` from the in-app browser; both answer
+ * `brc100:requestWallet` at once), or, only when framed, the XDM answer of a parent on BWALLETX_PARENT_ORIGINS.
+ *
+ * Never by `window.CWI` (0.5.6): another wallet (Metanet / BSV Desktop, Yours) can set or overwrite it, and treating
+ * whoever holds it as bWalletX handed our sign-in to that wallet. Every bWalletX build since 3 Oct 2026 announces.
+ * Resolves null after `ms` when no bWalletX announced (other wallets: discoverWallets).
  */
 declare function discoverBwalletX(ms?: number): Promise<FoundWallet | null>;
 /**
@@ -34,6 +40,8 @@ declare function discoverBwalletX(ms?: number): Promise<FoundWallet | null>;
  * open in bWalletX's in-app browser. Resolves null if nothing answered within `ms`.
  */
 declare function findBwalletX(ms?: number): Promise<WalletInterface | null>;
+/** True inside a frame (or when the parent can't be read). */
+declare const isFramed: () => boolean;
 /**
  * Wake the wallet before the click (call on pointerenter / focus / touchstart of your Connect button). Chrome stops an
  * idle extension worker after ~30 s, and a cold worker needs 1-3 s to reopen the wallet; this sends a liveness call
@@ -57,12 +65,32 @@ type SignInMethod = 'extension' | 'in-app' | 'pairing' | 'wallet';
 /**
  * Progress for the button label. 'finding': looking for a wallet (sub-second); 'opening': a wallet was found and its
  * approval is on the way ("Opening your wallet…"); 'pairing': no wallet in this browser, the QR is showing;
- * 'signing': the identity key arrived, the sign-in signature is being asked for.
+ * 'signing': the challenge arrived, the wallet's sign-in approval is being asked for.
  */
 type SignInStatus = 'finding' | 'opening' | 'pairing' | 'signing';
 interface SignInOptions {
-    /** Ask your server for a challenge for this identity key. */
-    challenge: (identityKey: string) => Promise<Challenge>;
+    /**
+     * Ask your server for a challenge. Since 0.5.5 it is called BEFORE the wallet is asked anything, and gets an identity
+     * key only when you pass `identityKey` (an identity you already connected) or set `challengeNeedsIdentityKey`;
+     * otherwise undefined. The 0.5.5 server helpers (createChallenge) accept no key, and verifySignIn binds the key the
+     * browser then claims to the signature. A pre-0.5.5 server that refuses a keyless challenge is detected and retried
+     * in the old order automatically.
+     */
+    challenge(identityKey?: string): Promise<Challenge>;
+    /**
+     * The identity key you already have from an earlier connect (reuse the connected identity): the wallet is then asked
+     * for the signature only. Without it, getPublicKey({ identityKey: true }) and createSignature go to the wallet
+     * together (Promise.all), so the wallet shows ONE sheet, not three.
+     */
+    identityKey?: string;
+    /**
+     * Servers older than 0.5.5 refuse a challenge without an identity key. Set true to use the old order straight away
+     * (identity key, then the challenge, then the signature: two wallet calls). Without it, the old order is used only
+     * after such a server has refused a keyless challenge.
+     */
+    challengeNeedsIdentityKey?: boolean;
+    /** Skip waitForAuthentication before signing (the provider already waited). Default false. */
+    skipWaitForAuthentication?: boolean;
     /** Use this wallet instead of looking for one. `method` is then 'wallet'. */
     wallet?: WalletInterface;
     /** How to show the QR and code if pairing is needed. Without it, pairing is not tried. */
@@ -89,10 +117,41 @@ declare function connectBwalletX(opts?: Pick<SignInOptions, 'wallet' | 'pairing'
     method: SignInMethod;
 }>;
 /**
- * Sign the server's challenge with the user's bWalletX identity key. Post the result's
- * identityKey, nonce and signature to your verify route.
+ * Wait for the user to unlock only when the wallet says it is locked. isAuthenticated never shows anything; an
+ * unconditional waitForAuthentication is not free: bWalletX answers it by fetching the site's manifest.json and, when
+ * that asks for permissions, shows a separate sheet, once per call.
+ */
+declare function waitIfLocked(wallet: WalletInterface): Promise<void>;
+/**
+ * True when a server refused a challenge because it wanted an identity key (createChallenge before 0.5.5 answers 400
+ * "identityKey must be a compressed public key (66 hex chars)").
+ */
+declare function challengeWantsIdentityKey(e: unknown): boolean;
+/**
+ * Sign the server's challenge with the user's bWalletX identity key. Post the result's identityKey, nonce and
+ * signature to your verify route.
+ *
+ * Wallet calls, in order:
+ *   1. the challenge comes from your server first (no wallet call);
+ *   2. getPublicKey({ identityKey: true }) and createSignature go to the wallet TOGETHER, so the wallet merges them
+ *      into one approval. With `identityKey` (already connected) only createSignature is asked for.
  */
 declare function signInWithBwalletX(opts: SignInOptions): Promise<SignInResult>;
+interface SignInAndVerifyOptions extends SignInOptions {
+    /** POST the result to your verify route; resolve with its JSON. A 401 (status on the error) means "sign-in failed". */
+    verify: (r: SignInResult) => Promise<Record<string, unknown>>;
+    /**
+     * A remembered identity key (rememberedIdentity()). Used like `identityKey` (one wallet call: the signature only),
+     * but if the server rejects the signature (another account is active now), it is dropped and the sign-in is retried
+     * with the key asked for.
+     */
+    identityKeyHint?: string;
+}
+/** signInWithBwalletX + your verify route, with the identity-hint fallback. */
+declare function signInAndVerify(opts: SignInAndVerifyOptions): Promise<{
+    result: SignInResult;
+    verified: Record<string, unknown>;
+}>;
 /** Where a sign-in failed: the wallet's identity prompt, the site's challenge endpoint, or the wallet's signature. */
 type SignInStage = 'identity' | 'challenge' | 'signature' | 'verify';
 
@@ -115,6 +174,38 @@ declare function renderButton(el: HTMLElement | string, opts?: ButtonOptions): H
  */
 declare function inOrder<T>(handle: (frame: T) => Promise<void> | void, onError?: (e: unknown) => void): (frame: T) => Promise<void>;
 
+/**
+ * The signed-in account as the badge shows it: paymail (best-effort lookup by identity key), a $handle label, a short
+ * key when there is no paymail, and the bAvatar picture (gold by default, generated for any key).
+ */
+declare const PAYMAIL_LOOKUP_URL = "https://pay.bwallet.space/api/paymail/lookup?key=";
+declare const BAVATAR_URL = "https://chat.bwalletx.com/api/bavatar/";
+/** 0266c1…7c83 */
+declare function shortKey(key: string): string;
+/** $alice for alice@bwalletx.com, a site handle as given, other paymails in full, else a short key. */
+declare function accountLabel(a: {
+    identityKey?: string | null;
+    paymail?: string | null;
+    handle?: string | null;
+}): string;
+/** The bAvatar for an identity key (a generated gold avatar when the user has not set one). */
+declare function avatarUrlFor(identityKey: string | null | undefined): string | null;
+/** The paymail for an identity key, or null. Best effort: never throws, one request per key per page. */
+declare function lookupPaymail(identityKey: string, url?: string): Promise<string | null>;
+/** True when the user said no in the wallet (BRC-100 denial, or a picker / sheet closed). */
+declare function isUserRejection(e: unknown): boolean;
+/** One plain line for an error: "Sign-in cancelled" for a no in the wallet, otherwise the gist. */
+declare function signInErrorText(e: unknown): string;
+/** localStorage key for the identity key that last signed in on this site (public data; a hint, never trusted). */
+declare const IDENTITY_HINT_KEY = "bwx:identityKey";
+/**
+ * The identity key that last signed in on this site, if any. Passing it to signInWithBwalletX makes a repeat sign-in
+ * ONE wallet call (createSignature only). It is only a hint: the server still checks the signature against it, and a
+ * wrong hint (another account) fails verification and is retried with the key asked for.
+ */
+declare function rememberedIdentity(): string | undefined;
+declare function rememberIdentity(key: string | null): void;
+
 /** An SVG QR code for `text` (error correction M). */
 declare function qrSvg(text: string): string;
 /**
@@ -149,6 +240,24 @@ declare function pairingModal(o?: PairingModalOptions): PairingOptions & {
 declare function pickWallet(options: WalletOption[], o?: {
     title?: string;
 }): Promise<WalletOption | null>;
+interface ChooseWalletOptions {
+    /** Default "Choose a wallet". */
+    title?: string;
+    /** Where "Get bWalletX" points. Default https://bwalletx.com/get */
+    getUrl?: string;
+    /**
+     * Offer "Desktop wallet" (Metanet / BSV Desktop on localhost). Default true. It probes localhost only when tapped
+     * (desktopOption), never while the chooser opens.
+     */
+    desktop?: boolean;
+}
+/**
+ * The wallet chooser (0.5.6). Without bWalletX in this browser, "Get bWalletX" comes first; then bWalletX on the
+ * phone, the other wallets that were detected, "Desktop wallet" (probes localhost only when tapped) and app-supplied
+ * options. Opened from "Other wallets" while bWalletX is here, bWalletX is the first, gold row.
+ * Resolves with the chosen option, or null when closed. "Get bWalletX" is a link and leaves the chooser open.
+ */
+declare function chooseWallet(options: readonly WalletOption[], o?: ChooseWalletOptions): Promise<WalletOption | null>;
 
 /**
  * Browser side of the access protocol: ask the wallet to sign the site's challenge and prove the
@@ -201,4 +310,44 @@ declare const WALLET_THEME_META = "bwalletx-theme";
 /** Declare (or with null, withdraw) the theme the wallet should wear for this page. No-op outside a browser. */
 declare function declareWalletTheme(theme: string | null | undefined): void;
 
-export { type AccessChallengeLike, AccessError, AccessResponse, BWALLETX_RDNS, type ButtonOptions, type Challenge, DEFAULT_DISCOVER_MS, type FoundBy, type FoundWallet, HoldingProof, LOGIN_PROTOCOL, LOGO_URL, type PairingModalOptions, PairingOptions, RDNS_EXTENSION, RDNS_MOBILE, type RequestAccessOptions, type RequestAccessResult, type SignInMethod, type SignInOptions, type SignInResult, type SignInStage, type SignInStatus, WALLET_THEME_META, WalletOption, bindPrewarm, connectBwalletX, declareWalletTheme, discoverBwalletX, findBwalletX, inOrder, isTouchDevice, pairingModal, pickWallet, prewarmBwalletX, proveHoldings, qrSvg, renderButton, requestAccess, signInWithBwalletX, throwIfAccessError, toAccessError };
+interface ConnectFlowOptions {
+    /** The wallets found (discoverWallets). */
+    list: WalletOption[];
+    /** Connect this option without asking. */
+    walletId?: string;
+    /** false: never show the chooser (bWalletX, else the phone; never another wallet unasked). Default true. */
+    picker?: boolean;
+    /** "Other wallets": show the chooser even when bWalletX is here. */
+    chooser?: boolean;
+    /**
+     * bWalletX first (0.5.6, default true): bWalletX in this browser is connected with no chooser; without it the
+     * chooser opens ("Get bWalletX" first) and no other wallet is connected unless picked. false: the 0.5.5 rule.
+     */
+    fastPath?: boolean;
+    /** Show the chooser; resolves null when closed. chooseWallet (modal.ts) or your own UI. */
+    pick: (list: WalletOption[]) => Promise<WalletOption | null>;
+    /** With verifyUrl: sign in after connecting. */
+    challengeUrl?: string;
+    verifyUrl?: string;
+    challengeNeedsIdentityKey?: boolean;
+    /** POST JSON; throws with `status` on a non-2xx answer. */
+    post: (url: string, body: unknown) => Promise<Record<string, unknown>>;
+    /** Called once per attempt with { walletType, substrate, outcome, ms }. No keys, addresses or identity data. */
+    onAttempt?: AttemptHook;
+}
+interface ConnectFlowResult {
+    connected: ConnectedWallet;
+    identityKey: string | null;
+    handle: string | null;
+    paymail: string | null;
+    signedIn: boolean;
+    /** 'bwalletx' for bWalletX, else the wallet's rdns / option id. */
+    walletType: string;
+    substrate: Substrate;
+    /** Why this wallet: 'bwalletx' (fast path), 'chooser' (picked), 'requested' (walletId), … */
+    reason: ChoiceReason;
+}
+/** Resolves null when the user closed the chooser. Throws NOT_FOUND when there is nothing to connect. */
+declare function runConnect(o: ConnectFlowOptions): Promise<ConnectFlowResult | null>;
+
+export { type AccessChallengeLike, AccessError, AccessResponse, AttemptHook, BAVATAR_URL, BWALLETX_RDNS, type ButtonOptions, type Challenge, ChoiceReason, type ChooseWalletOptions, type ConnectFlowOptions, type ConnectFlowResult, ConnectedWallet, DEFAULT_DISCOVER_MS, type FoundBy, type FoundWallet, HoldingProof, IDENTITY_HINT_KEY, LOGIN_PROTOCOL, LOGO_URL, PAYMAIL_LOOKUP_URL, type PairingModalOptions, PairingOptions, RDNS_EXTENSION, RDNS_MOBILE, type RequestAccessOptions, type RequestAccessResult, type SignInAndVerifyOptions, type SignInMethod, type SignInOptions, type SignInResult, type SignInStage, type SignInStatus, Substrate, WALLET_THEME_META, WalletOption, accountLabel, avatarUrlFor, bindPrewarm, challengeWantsIdentityKey, chooseWallet, connectBwalletX, declareWalletTheme, discoverBwalletX, findBwalletX, inOrder, isFramed, isTouchDevice, isUserRejection, lookupPaymail, pairingModal, pickWallet, prewarmBwalletX, proveHoldings, qrSvg, rememberIdentity, rememberedIdentity, renderButton, requestAccess, runConnect, shortKey, signInAndVerify, signInErrorText, signInWithBwalletX, throwIfAccessError, toAccessError, waitIfLocked };