@bwalletx/connect 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,148 @@
+import { WalletInterface, WalletProtocol } from '@bsv/sdk';
+
+/** Ids bWalletX announces in BRC-100 wallet discovery. */
+declare const RDNS_EXTENSION = "com.bwalletx.extension";
+declare const RDNS_MOBILE = "space.bwallet.mobile";
+declare const BWALLETX_RDNS: readonly ["com.bwalletx.extension", "space.bwallet.mobile"];
+type FoundBy = 'extension' | 'in-app';
+interface FoundWallet {
+    wallet: WalletInterface;
+    /** 'extension' for the Chrome extension; 'in-app' inside the bWalletX app's own browser. */
+    method: FoundBy;
+    rdns: string | null;
+}
+/**
+ * Like findBwalletX, but also says which bWalletX answered.
+ * Order: a BRC-100 announcement with a bWalletX rdns; then `window.CWI` (set by the in-app
+ * browser, and by older builds that do not announce); otherwise null.
+ */
+declare function discoverBwalletX(ms?: number): Promise<FoundWallet | null>;
+/**
+ * Find bWalletX in this page: the extension on a computer, or the wallet itself when the page is
+ * open in bWalletX's in-app browser. Resolves null if nothing answered within `ms`.
+ */
+declare function findBwalletX(ms?: number): Promise<WalletInterface | null>;
+
+/** localStorage-shaped storage. Methods may be sync or async. */
+interface PairStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/** The minimum of the browser WebSocket API this package uses (the `ws` package also fits). */
+interface SocketLike {
+    readonly readyState: number;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onclose: ((ev: unknown) => void) | null;
+    send(data: string): void;
+    close(): void;
+}
+type SocketFactory = (url: string) => SocketLike;
+interface PairConnectionOptions {
+    /** Where the pairing is kept so it survives a reload. Default: localStorage, else memory only. */
+    storage?: PairStorage | null;
+    /** Storage key. Default 'bwalletx.connect.pairing.v1'. */
+    storageKey?: string;
+    /** Opens a socket. Default: the global WebSocket. Pass one to run in Node or to test. */
+    socket?: SocketFactory;
+    /** Per-call timeout in ms. Default 120000. */
+    callTimeoutMs?: number;
+}
+interface PairingOptions extends PairConnectionOptions {
+    /** Show this link as a QR code, and as text to copy (web.bwalletx.com takes it pasted). */
+    onLink: (link: string) => void;
+    /** Show this 4-digit code. The wallet shows the same one; the user checks they match. */
+    onCode: (code: string) => void;
+    signal?: AbortSignal;
+    /** Relay host. Default relay.bwallet.space. */
+    relay?: string;
+    /** This page's origin, as the relay will see it. Default location.origin. */
+    origin?: string;
+}
+/** A BRC-100 wallet whose every call goes, end-to-end encrypted, to the paired phone or web wallet. */
+type PairedWallet = WalletInterface & {
+    /** Close the relay connection. The pairing stays stored; the next call reconnects. */
+    close(): void;
+    /** Tell the wallet to unpair, close, and delete the stored pairing. */
+    forget(): Promise<void>;
+};
+/**
+ * Pair with bWalletX on a phone (scan the QR) or web.bwalletx.com (paste the link).
+ * Resolves with a wallet once the user taps Connect. The pairing is stored (see `storage`) so
+ * `restorePairing()` can reconnect after a reload without a new QR.
+ */
+declare function pairBwalletX(opts: PairingOptions): Promise<PairedWallet>;
+/**
+ * The wallet from a pairing stored by an earlier `pairBwalletX`, or null if there is none.
+ * It connects on the first call. The wallet must still have this site paired.
+ */
+declare function restorePairing(opts?: PairConnectionOptions): Promise<PairedWallet | null>;
+/** Delete the stored pairing without telling the wallet. */
+declare function clearPairing(opts?: Pick<PairConnectionOptions, 'storage' | 'storageKey'>): Promise<void>;
+
+/** Security level 2, a protocol name used for nothing else. */
+declare const LOGIN_PROTOCOL: WalletProtocol;
+/** What your server's challenge route returns (createChallenge from '@bwalletx/connect/server'). */
+interface Challenge {
+    nonce: string;
+    message: string;
+    keyID: string;
+    protocolID?: WalletProtocol;
+}
+type SignInMethod = 'extension' | 'in-app' | 'pairing' | 'wallet';
+interface SignInOptions {
+    /** Ask your server for a challenge for this identity key. */
+    challenge: (identityKey: string) => Promise<Challenge>;
+    /** 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. */
+    pairing?: PairingOptions;
+    /** Reuse a pairing stored by an earlier sign-in before showing a new QR. Default true. */
+    reusePairing?: boolean;
+    /** How long to wait for the extension or in-app browser to answer, in ms. Default 1200. */
+    discoverMs?: number;
+}
+interface SignInResult {
+    identityKey: string;
+    /** DER signature as number[], ready to post to verifySignIn. */
+    signature: number[];
+    nonce: string;
+    method: SignInMethod;
+    /** The wallet that signed. Keep it to make more calls. */
+    wallet: WalletInterface;
+}
+/** Find a wallet: extension or in-app browser first, then a stored pairing, then a new pairing. */
+declare function connectBwalletX(opts?: Pick<SignInOptions, 'wallet' | 'pairing' | 'reusePairing' | 'discoverMs'>): Promise<{
+    wallet: WalletInterface;
+    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.
+ */
+declare function signInWithBwalletX(opts: SignInOptions): Promise<SignInResult>;
+
+declare const LOGO_URL = "https://bwalletx.com/logo.svg";
+interface ButtonOptions {
+    /** Second line under the label. Default "also works with bWallet". false hides it. */
+    subtitle?: string | false;
+    onClick?: (button: HTMLButtonElement) => void;
+}
+/** Put the gold "Sign in with bWalletX" button into `el` (replacing its contents). */
+declare function renderButton(el: HTMLElement | string, opts?: ButtonOptions): HTMLButtonElement;
+
+/**
+ * Wrap an async frame handler so frames are handled one at a time, in arrival order.
+ *
+ * WebSocket `onmessage` does not wait for an async handler. The phone sends its plain `hello`
+ * and then, as soon as the user taps Connect, a sealed `ready`. If the handler for `hello` is
+ * still deriving the session key when `ready` arrives, a naive handler sees no key yet and drops
+ * `ready`, so pairing never finishes. Chaining every frame onto one promise fixes that.
+ */
+declare function inOrder<T>(handle: (frame: T) => Promise<void> | void, onError?: (e: unknown) => void): (frame: T) => Promise<void>;
+
+export { BWALLETX_RDNS, type ButtonOptions, type Challenge, type FoundBy, type FoundWallet, LOGIN_PROTOCOL, LOGO_URL, type PairConnectionOptions, type PairStorage, type PairedWallet, type PairingOptions, RDNS_EXTENSION, RDNS_MOBILE, type SignInMethod, type SignInOptions, type SignInResult, type SocketFactory, type SocketLike, clearPairing, connectBwalletX, discoverBwalletX, findBwalletX, inOrder, pairBwalletX, renderButton, restorePairing, signInWithBwalletX };

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+import { WalletInterface, WalletProtocol } from '@bsv/sdk';
+
+/** Ids bWalletX announces in BRC-100 wallet discovery. */
+declare const RDNS_EXTENSION = "com.bwalletx.extension";
+declare const RDNS_MOBILE = "space.bwallet.mobile";
+declare const BWALLETX_RDNS: readonly ["com.bwalletx.extension", "space.bwallet.mobile"];
+type FoundBy = 'extension' | 'in-app';
+interface FoundWallet {
+    wallet: WalletInterface;
+    /** 'extension' for the Chrome extension; 'in-app' inside the bWalletX app's own browser. */
+    method: FoundBy;
+    rdns: string | null;
+}
+/**
+ * Like findBwalletX, but also says which bWalletX answered.
+ * Order: a BRC-100 announcement with a bWalletX rdns; then `window.CWI` (set by the in-app
+ * browser, and by older builds that do not announce); otherwise null.
+ */
+declare function discoverBwalletX(ms?: number): Promise<FoundWallet | null>;
+/**
+ * Find bWalletX in this page: the extension on a computer, or the wallet itself when the page is
+ * open in bWalletX's in-app browser. Resolves null if nothing answered within `ms`.
+ */
+declare function findBwalletX(ms?: number): Promise<WalletInterface | null>;
+
+/** localStorage-shaped storage. Methods may be sync or async. */
+interface PairStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/** The minimum of the browser WebSocket API this package uses (the `ws` package also fits). */
+interface SocketLike {
+    readonly readyState: number;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onclose: ((ev: unknown) => void) | null;
+    send(data: string): void;
+    close(): void;
+}
+type SocketFactory = (url: string) => SocketLike;
+interface PairConnectionOptions {
+    /** Where the pairing is kept so it survives a reload. Default: localStorage, else memory only. */
+    storage?: PairStorage | null;
+    /** Storage key. Default 'bwalletx.connect.pairing.v1'. */
+    storageKey?: string;
+    /** Opens a socket. Default: the global WebSocket. Pass one to run in Node or to test. */
+    socket?: SocketFactory;
+    /** Per-call timeout in ms. Default 120000. */
+    callTimeoutMs?: number;
+}
+interface PairingOptions extends PairConnectionOptions {
+    /** Show this link as a QR code, and as text to copy (web.bwalletx.com takes it pasted). */
+    onLink: (link: string) => void;
+    /** Show this 4-digit code. The wallet shows the same one; the user checks they match. */
+    onCode: (code: string) => void;
+    signal?: AbortSignal;
+    /** Relay host. Default relay.bwallet.space. */
+    relay?: string;
+    /** This page's origin, as the relay will see it. Default location.origin. */
+    origin?: string;
+}
+/** A BRC-100 wallet whose every call goes, end-to-end encrypted, to the paired phone or web wallet. */
+type PairedWallet = WalletInterface & {
+    /** Close the relay connection. The pairing stays stored; the next call reconnects. */
+    close(): void;
+    /** Tell the wallet to unpair, close, and delete the stored pairing. */
+    forget(): Promise<void>;
+};
+/**
+ * Pair with bWalletX on a phone (scan the QR) or web.bwalletx.com (paste the link).
+ * Resolves with a wallet once the user taps Connect. The pairing is stored (see `storage`) so
+ * `restorePairing()` can reconnect after a reload without a new QR.
+ */
+declare function pairBwalletX(opts: PairingOptions): Promise<PairedWallet>;
+/**
+ * The wallet from a pairing stored by an earlier `pairBwalletX`, or null if there is none.
+ * It connects on the first call. The wallet must still have this site paired.
+ */
+declare function restorePairing(opts?: PairConnectionOptions): Promise<PairedWallet | null>;
+/** Delete the stored pairing without telling the wallet. */
+declare function clearPairing(opts?: Pick<PairConnectionOptions, 'storage' | 'storageKey'>): Promise<void>;
+
+/** Security level 2, a protocol name used for nothing else. */
+declare const LOGIN_PROTOCOL: WalletProtocol;
+/** What your server's challenge route returns (createChallenge from '@bwalletx/connect/server'). */
+interface Challenge {
+    nonce: string;
+    message: string;
+    keyID: string;
+    protocolID?: WalletProtocol;
+}
+type SignInMethod = 'extension' | 'in-app' | 'pairing' | 'wallet';
+interface SignInOptions {
+    /** Ask your server for a challenge for this identity key. */
+    challenge: (identityKey: string) => Promise<Challenge>;
+    /** 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. */
+    pairing?: PairingOptions;
+    /** Reuse a pairing stored by an earlier sign-in before showing a new QR. Default true. */
+    reusePairing?: boolean;
+    /** How long to wait for the extension or in-app browser to answer, in ms. Default 1200. */
+    discoverMs?: number;
+}
+interface SignInResult {
+    identityKey: string;
+    /** DER signature as number[], ready to post to verifySignIn. */
+    signature: number[];
+    nonce: string;
+    method: SignInMethod;
+    /** The wallet that signed. Keep it to make more calls. */
+    wallet: WalletInterface;
+}
+/** Find a wallet: extension or in-app browser first, then a stored pairing, then a new pairing. */
+declare function connectBwalletX(opts?: Pick<SignInOptions, 'wallet' | 'pairing' | 'reusePairing' | 'discoverMs'>): Promise<{
+    wallet: WalletInterface;
+    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.
+ */
+declare function signInWithBwalletX(opts: SignInOptions): Promise<SignInResult>;
+
+declare const LOGO_URL = "https://bwalletx.com/logo.svg";
+interface ButtonOptions {
+    /** Second line under the label. Default "also works with bWallet". false hides it. */
+    subtitle?: string | false;
+    onClick?: (button: HTMLButtonElement) => void;
+}
+/** Put the gold "Sign in with bWalletX" button into `el` (replacing its contents). */
+declare function renderButton(el: HTMLElement | string, opts?: ButtonOptions): HTMLButtonElement;
+
+/**
+ * Wrap an async frame handler so frames are handled one at a time, in arrival order.
+ *
+ * WebSocket `onmessage` does not wait for an async handler. The phone sends its plain `hello`
+ * and then, as soon as the user taps Connect, a sealed `ready`. If the handler for `hello` is
+ * still deriving the session key when `ready` arrives, a naive handler sees no key yet and drops
+ * `ready`, so pairing never finishes. Chaining every frame onto one promise fixes that.
+ */
+declare function inOrder<T>(handle: (frame: T) => Promise<void> | void, onError?: (e: unknown) => void): (frame: T) => Promise<void>;
+
+export { BWALLETX_RDNS, type ButtonOptions, type Challenge, type FoundBy, type FoundWallet, LOGIN_PROTOCOL, LOGO_URL, type PairConnectionOptions, type PairStorage, type PairedWallet, type PairingOptions, RDNS_EXTENSION, RDNS_MOBILE, type SignInMethod, type SignInOptions, type SignInResult, type SocketFactory, type SocketLike, clearPairing, connectBwalletX, discoverBwalletX, findBwalletX, inOrder, pairBwalletX, renderButton, restorePairing, signInWithBwalletX };