@bwalletx/connect 0.4.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.5.3 (unreleased)
+
+- **Phones get "Open bWalletX", not a QR.** On a touch device (`isTouchDevice()`), `pairingModal()` no longer shows a QR the user would have to scan with the same phone. It shows **Open bWalletX**, a link to the pairing universal link (`https://www.bwallet.space/pair?…`, the iOS universal link / Android app link the app already handles), plus **Use web.bwalletx.com instead** (copies the link and opens the web wallet to paste it), and the match code. The page keeps waiting on the pairing channel, so the user approves in the wallet and comes back. Desktops still get the QR. Force either with `pairingModal({ mode: 'qr' | 'app' })`.
+
+## 0.5.2 (unreleased)
+
+- **Security: framed pages only ask bWalletX itself over XDM.** `findBwalletX` / `discoverBwalletX` in a frame used to post to whatever page framed it and take its answers, so any page that framed your site became "the wallet" (saw every call, could return a fake txid). Now the parent's origin (from `location.ancestorOrigins`, else the referrer) must be one of `BWALLETX_PARENT_ORIGINS` (web.bwalletx.com, bwallet.space, the iOS/Android/Desktop app shells, the Chrome extension); messages go to that exact origin and only its answers count. `probeXdm(ms, allowed)` takes your own list if you host the wallet elsewhere.
+- Docs: verify payments on your server (`verifyPayment`); never trust a txid from the page.
+
+## 0.5.0 (unreleased)
+
+- **Site theme in the wallet**: `BwalletXProvider theme="npgx"` (or `declareWalletTheme('npgx')`) declares `<meta name="bwalletx-theme">` while connecting/connected and removes it on disconnect. bWalletX wears that theme for this origin only, from the themes it bundles (brand editions locked to their own sites); only the id is sent, never colours or CSS.
+- Sign-in errors carry `err.stage` (`identity` | `challenge` | `signature` | `verify`) with the original message, so a site can say what actually failed instead of guessing from the text.
+- **Access protocol v1 ($401 identity / $403 token-gated access)**, spec in `docs/ACCESS-PROTOCOL.md`. Standard BRC-100 calls only, so any BRC-100 wallet works.
+- Client: `requestAccess()` signs the site's challenge and proves the keys that hold the token (`proveHoldings()`). Errors are `AccessError` with a protocol code.
+- Server: `createAccessChallenge`, `verifyAccess`, `checkTokenHolding`, plus `oneSatResolver()` (1Sat indexer) and `bitSignResolver()` (identity level / KYC). Fails closed: an indexer outage is `indexer_unavailable`, never a grant.
+- Next.js: `createBwalletXAccess()` gives challenge, verify, status and logout routes, a signed access cookie, and `getAccess()`, which re-checks holdings every `recheckEvery` seconds so selling the tokens ends access.
+- `<bwalletx-signin require-token="bsv21:…" min="100">` runs the access flow and emits `bwalletx-access-granted` / `bwalletx-access-denied`.
+- Protocol videos and posters in `assets/protocol/` (401 green, 402 blue, 403 red), exported as `PROTOCOL_MEDIA`.
+
 ## 0.4.1 (2026-10-12)
 
 - React: `BwalletXProvider` and `BwalletxSignin` declare `ReactElement` return types, so they type-check as JSX under React 18 `@types/react`.

package/README.md

@@ -99,6 +99,8 @@ function Account() {
 
 ## Payments
 
+Other bCorp apps: use `tip()` for the default Tip button (the same one-sheet tip bWalletX shows on artists, NFTs, chat, Friends and Spaces).
+
 ```ts
 import { pay, tip, buyToken } from '@bwalletx/connect';
 
@@ -110,7 +112,9 @@ await buyToken(wallet, { token: '$BOASE', amount: 100, quote: (q) => fetch('/api
 
 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.
 
-On the server, check the payment before you deliver anything:
+**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.
+Deliver nothing until your server has checked the payment:
 
 ```ts
 import { verifyPayment } from '@bwalletx/connect/server';
@@ -134,7 +138,7 @@ Every expected output has to be matched by a different output that carries at le
 - 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.
+`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.
 
 ## Migrating from HandCash Connect
 

package/dist/access-Dp0eKIOc.d.cts

@@ -0,0 +1,118 @@
+import { WalletProtocol } from '@bsv/sdk';
+
+/**
+ * $401 / $402 / $403 access protocol, version 1. Shared by sites (client + server) and wallets.
+ * The full spec is docs/ACCESS-PROTOCOL.md. Pure: no I/O, @bsv/sdk types only.
+ *
+ *   401 identity  "prove who you are (at identity level N, or KYC'd)"
+ *   402 payment   "pay for this" (the challenge format is reserved; payment itself uses pay())
+ *   403 access    "prove you hold N of token X (or N basis points of its supply)"
+ */
+
+declare const ACCESS_VERSION: 1;
+/** Security level 2, a protocol name used for nothing else. Wallets recognise it and show the kind's video. */
+declare const ACCESS_PROTOCOL: WalletProtocol;
+/** How long a challenge is valid. */
+declare const ACCESS_CHALLENGE_LIFETIME_S = 120;
+/** At most this many holding proofs are read from one response. */
+declare const MAX_HOLDING_PROOFS = 50;
+type AccessKind = '401' | '402' | '403';
+interface TokenRequirement {
+    /** 'bsv21:<txid>_<vout>' */
+    id: string;
+    /** Minimum raw (unscaled, integer string) amount. */
+    min?: string;
+    /** Minimum in basis points of total supply (1 = 0.01%, 10000 = 100%). */
+    minBps?: number;
+}
+interface AccessRequirement {
+    token?: TokenRequirement;
+    /** $401 identity level (bit-sign strands): 1 Basic, 2 Verified, 3 Strong, 4 Sovereign (Veriff). */
+    identityLevel?: number;
+    /** A live KYC credential is required. */
+    kyc?: boolean;
+}
+/** What the wallet signs, as canonical JSON. Times are seconds since the epoch. */
+interface AccessChallenge {
+    v: 1;
+    kind: AccessKind;
+    origin: string;
+    nonce: string;
+    iat: number;
+    exp: number;
+    /** The identity key the site expects. A different wallet account is `wrong_account`. */
+    sub?: string;
+    require: AccessRequirement;
+}
+/** A key that locks some of the required token, proving control by signing the same challenge bytes. */
+interface HoldingProof {
+    /** Compressed public key hex of the key locking the outputs. */
+    pubkey: string;
+    /** DER signature by that key over SHA-256(challenge bytes), as BRC-100 createSignature returns. */
+    signature: number[];
+    /** Optional hint: outpoints ('txid_vout') this key holds. Servers must not trust it. */
+    outpoints?: string[];
+}
+/** What the wallet (via requestAccess) posts back to the site. */
+interface AccessResponse {
+    v: 1;
+    /** The challenge string exactly as issued. */
+    challenge: string;
+    identityKey: string;
+    /** DER signature: createSignature({ protocolID: ACCESS_PROTOCOL, keyID: nonce, counterparty: 'anyone', data: challenge bytes }). */
+    signature: number[];
+    holdings?: HoldingProof[];
+}
+type AccessErrorCode = 'not_installed' | 'user_rejected' | 'wrong_account' | 'insufficient_tokens' | 'identity_level_too_low' | 'kyc_required' | 'indexer_unavailable' | 'expired' | 'replay' | 'invalid_signature' | 'bad_request';
+/** The HTTP status a site should answer each code with. */
+declare const ACCESS_ERROR_STATUS: Record<AccessErrorCode, number>;
+interface AccessErrorBody {
+    error: AccessErrorCode;
+    message: string;
+    /** insufficient_tokens: raw amounts; identity_level_too_low: levels. */
+    have?: string | number;
+    need?: string | number;
+}
+declare class AccessError extends Error {
+    readonly code: AccessErrorCode;
+    readonly have?: string | number;
+    readonly need?: string | number;
+    constructor(code: AccessErrorCode, message?: string, extra?: {
+        have?: string | number;
+        need?: string | number;
+    });
+    toJSON(): AccessErrorBody;
+}
+/** One video + poster + colour per kind, so wallets and sites show the same thing. Paths are inside the package. */
+declare const PROTOCOL_MEDIA: Record<AccessKind, {
+    name: string;
+    color: string;
+    video: string;
+    poster: string;
+}>;
+/** Media URLs on a CDN (unpkg) for a given package version. */
+declare function protocolMediaUrl(kind: AccessKind, which: 'video' | 'poster', version?: string): string;
+/**
+ * Canonical JSON: object keys sorted by code unit, no whitespace, undefined members dropped.
+ * Only strings, finite numbers, booleans, null, arrays and plain objects are allowed.
+ */
+declare function canonicalJson(v: unknown): string;
+/** The bytes every signature in the protocol covers: UTF-8 of the challenge string. */
+declare function challengeBytes(challenge: string): number[];
+/** Throws AccessError('bad_request') if the requirement is malformed. Returns a normalised copy. */
+declare function normaliseRequirement(r: unknown): AccessRequirement;
+/** The kind a requirement implies: any token → 403; otherwise 401. */
+declare function kindFor(r: AccessRequirement): AccessKind;
+/** Parse and validate a challenge string. Throws AccessError('bad_request'). Does not check expiry. */
+declare function parseAccessChallenge(s: unknown): AccessChallenge;
+/** Raw amount needed for a token requirement, given total supply (needed only for minBps). Rounds up. */
+declare function tokenNeedRaw(t: TokenRequirement, supplyRaw?: string): string;
+/** Compare unscaled integer strings. Fails closed on malformed input. */
+declare function atLeastRaw(have: string, need: string): boolean;
+/** A user-readable line for an error code. */
+declare function accessErrorMessage(code: AccessErrorCode, e?: {
+    have?: string | number;
+    need?: string | number;
+}): string;
+
+export { AccessError as A, type HoldingProof as H, MAX_HOLDING_PROOFS as M, PROTOCOL_MEDIA as P, type TokenRequirement as T, type AccessRequirement as a, type AccessResponse as b, type AccessKind as c, ACCESS_PROTOCOL as d, ACCESS_CHALLENGE_LIFETIME_S as e, ACCESS_ERROR_STATUS as f, ACCESS_VERSION as g, type AccessChallenge as h, type AccessErrorBody as i, type AccessErrorCode as j, accessErrorMessage as k, atLeastRaw as l, canonicalJson as m, challengeBytes as n, kindFor as o, normaliseRequirement as p, parseAccessChallenge as q, protocolMediaUrl as r, tokenNeedRaw as t };

package/dist/access-Dp0eKIOc.d.ts

@@ -0,0 +1,118 @@
+import { WalletProtocol } from '@bsv/sdk';
+
+/**
+ * $401 / $402 / $403 access protocol, version 1. Shared by sites (client + server) and wallets.
+ * The full spec is docs/ACCESS-PROTOCOL.md. Pure: no I/O, @bsv/sdk types only.
+ *
+ *   401 identity  "prove who you are (at identity level N, or KYC'd)"
+ *   402 payment   "pay for this" (the challenge format is reserved; payment itself uses pay())
+ *   403 access    "prove you hold N of token X (or N basis points of its supply)"
+ */
+
+declare const ACCESS_VERSION: 1;
+/** Security level 2, a protocol name used for nothing else. Wallets recognise it and show the kind's video. */
+declare const ACCESS_PROTOCOL: WalletProtocol;
+/** How long a challenge is valid. */
+declare const ACCESS_CHALLENGE_LIFETIME_S = 120;
+/** At most this many holding proofs are read from one response. */
+declare const MAX_HOLDING_PROOFS = 50;
+type AccessKind = '401' | '402' | '403';
+interface TokenRequirement {
+    /** 'bsv21:<txid>_<vout>' */
+    id: string;
+    /** Minimum raw (unscaled, integer string) amount. */
+    min?: string;
+    /** Minimum in basis points of total supply (1 = 0.01%, 10000 = 100%). */
+    minBps?: number;
+}
+interface AccessRequirement {
+    token?: TokenRequirement;
+    /** $401 identity level (bit-sign strands): 1 Basic, 2 Verified, 3 Strong, 4 Sovereign (Veriff). */
+    identityLevel?: number;
+    /** A live KYC credential is required. */
+    kyc?: boolean;
+}
+/** What the wallet signs, as canonical JSON. Times are seconds since the epoch. */
+interface AccessChallenge {
+    v: 1;
+    kind: AccessKind;
+    origin: string;
+    nonce: string;
+    iat: number;
+    exp: number;
+    /** The identity key the site expects. A different wallet account is `wrong_account`. */
+    sub?: string;
+    require: AccessRequirement;
+}
+/** A key that locks some of the required token, proving control by signing the same challenge bytes. */
+interface HoldingProof {
+    /** Compressed public key hex of the key locking the outputs. */
+    pubkey: string;
+    /** DER signature by that key over SHA-256(challenge bytes), as BRC-100 createSignature returns. */
+    signature: number[];
+    /** Optional hint: outpoints ('txid_vout') this key holds. Servers must not trust it. */
+    outpoints?: string[];
+}
+/** What the wallet (via requestAccess) posts back to the site. */
+interface AccessResponse {
+    v: 1;
+    /** The challenge string exactly as issued. */
+    challenge: string;
+    identityKey: string;
+    /** DER signature: createSignature({ protocolID: ACCESS_PROTOCOL, keyID: nonce, counterparty: 'anyone', data: challenge bytes }). */
+    signature: number[];
+    holdings?: HoldingProof[];
+}
+type AccessErrorCode = 'not_installed' | 'user_rejected' | 'wrong_account' | 'insufficient_tokens' | 'identity_level_too_low' | 'kyc_required' | 'indexer_unavailable' | 'expired' | 'replay' | 'invalid_signature' | 'bad_request';
+/** The HTTP status a site should answer each code with. */
+declare const ACCESS_ERROR_STATUS: Record<AccessErrorCode, number>;
+interface AccessErrorBody {
+    error: AccessErrorCode;
+    message: string;
+    /** insufficient_tokens: raw amounts; identity_level_too_low: levels. */
+    have?: string | number;
+    need?: string | number;
+}
+declare class AccessError extends Error {
+    readonly code: AccessErrorCode;
+    readonly have?: string | number;
+    readonly need?: string | number;
+    constructor(code: AccessErrorCode, message?: string, extra?: {
+        have?: string | number;
+        need?: string | number;
+    });
+    toJSON(): AccessErrorBody;
+}
+/** One video + poster + colour per kind, so wallets and sites show the same thing. Paths are inside the package. */
+declare const PROTOCOL_MEDIA: Record<AccessKind, {
+    name: string;
+    color: string;
+    video: string;
+    poster: string;
+}>;
+/** Media URLs on a CDN (unpkg) for a given package version. */
+declare function protocolMediaUrl(kind: AccessKind, which: 'video' | 'poster', version?: string): string;
+/**
+ * Canonical JSON: object keys sorted by code unit, no whitespace, undefined members dropped.
+ * Only strings, finite numbers, booleans, null, arrays and plain objects are allowed.
+ */
+declare function canonicalJson(v: unknown): string;
+/** The bytes every signature in the protocol covers: UTF-8 of the challenge string. */
+declare function challengeBytes(challenge: string): number[];
+/** Throws AccessError('bad_request') if the requirement is malformed. Returns a normalised copy. */
+declare function normaliseRequirement(r: unknown): AccessRequirement;
+/** The kind a requirement implies: any token → 403; otherwise 401. */
+declare function kindFor(r: AccessRequirement): AccessKind;
+/** Parse and validate a challenge string. Throws AccessError('bad_request'). Does not check expiry. */
+declare function parseAccessChallenge(s: unknown): AccessChallenge;
+/** Raw amount needed for a token requirement, given total supply (needed only for minBps). Rounds up. */
+declare function tokenNeedRaw(t: TokenRequirement, supplyRaw?: string): string;
+/** Compare unscaled integer strings. Fails closed on malformed input. */
+declare function atLeastRaw(have: string, need: string): boolean;
+/** A user-readable line for an error code. */
+declare function accessErrorMessage(code: AccessErrorCode, e?: {
+    have?: string | number;
+    need?: string | number;
+}): string;
+
+export { AccessError as A, type HoldingProof as H, MAX_HOLDING_PROOFS as M, PROTOCOL_MEDIA as P, type TokenRequirement as T, type AccessRequirement as a, type AccessResponse as b, type AccessKind as c, ACCESS_PROTOCOL as d, ACCESS_CHALLENGE_LIFETIME_S as e, ACCESS_ERROR_STATUS as f, ACCESS_VERSION as g, type AccessChallenge as h, type AccessErrorBody as i, type AccessErrorCode as j, accessErrorMessage as k, atLeastRaw as l, canonicalJson as m, challengeBytes as n, kindFor as o, normaliseRequirement as p, parseAccessChallenge as q, protocolMediaUrl as r, tokenNeedRaw as t };