@bsv/wallet-toolbox-client 2.4.4 → 2.4.20

package/LICENSE.txt

@@ -0,0 +1,58 @@
+Open BSV License Version 6 – granted by BSV Association, Alpenstrasse 15, 6300
+Zug, Switzerland (CHE-427.008.338) ("Licensor"), to you as a user (henceforth
+"You", "User" or "Licensee").
+
+For the purposes of this license, the definitions below have the following
+meanings:
+
+"Bitcoin Protocol" means the protocol implementation, cryptographic rules,
+network protocols, and consensus mechanisms in the Bitcoin White Paper as
+described here https://protocol.bsvblockchain.org.
+
+"Bitcoin White Paper" means the paper entitled 'Bitcoin: A Peer-to-Peer
+Electronic Cash System' published by 'Satoshi Nakamoto' in October 2008.
+
+"BSV Blockchain" means:
+
+  (a) the Bitcoin blockchain containing block height #556767 with the hash
+      "000000000000000001d956714215d96ffc00e0afda4cd0a96c96f8d802b1662b" and
+      that contains the longest honest persistent chain of blocks which has been
+      produced in a manner which is consistent with the rules set forth in the
+      Network Access Rules; and
+  (b) the test blockchains that contain the longest honest persistent chains of
+      blocks which has been produced in a manner which is consistent with the
+      rules set forth in the Network Access Rules.
+
+"Network Access Rules" or "Rules" means the set of rules regulating the
+relationship between BSV Association and the nodes on BSV based on the Bitcoin
+Protocol rules and those set out in the Bitcoin White Paper, and available here
+https://bsvblockchain.org/network-access-rules.
+
+"Software" means the software the subject of this license, including any/all
+intellectual property rights therein and associated documentation files.
+
+BSV Association grants permission, free of charge and on a non-exclusive basis
+to any person obtaining a copy of the Software to deal in the Software, including
+without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to and conditioned upon the following
+conditions:
+
+1 - The text "© BSV Association", and this license shall be included in all
+copies or substantial portions of the Software.
+
+2 - The Software, and any software that is derived from the Software or parts
+thereof, may only be used exclusively on the BSV Blockchain.
+
+For the avoidance of doubt, this license is granted subject to and conditioned
+upon your compliance with these terms only and is limited to uses on the BSV
+Blockchain. Any exercise of rights not compliant with these terms including
+use not for the BSV Blockchain is deemed outside the scope of the license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES REGARDING ENTITLEMENT,
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS THEREOF BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@bsv/wallet-toolbox-client)](https://www.npmjs.com/package/@bsv/wallet-toolbox-client)
 [![npm downloads](https://img.shields.io/npm/dm/@bsv/wallet-toolbox-client)](https://www.npmjs.com/package/@bsv/wallet-toolbox-client)
 
-Browser build of [`@bsv/wallet-toolbox`](https://www.npmjs.com/package/@bsv/wallet-toolbox) — the reference [BRC-100](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0100.md) wallet implementation. Same wallet, signer, services, and monitor APIs as the full package, with Node-only storage backends (Knex / SQLite / MySQL) excluded so the bundle is small and safe to ship to browsers.
+Browser build of [`@bsv/wallet-toolbox`](https://www.npmjs.com/package/@bsv/wallet-toolbox) — the reference [BRC-100](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0100.md) wallet implementation. It provides browser-safe wallet, signer, services, monitor, local IndexedDB, and remote storage APIs without the full package's Node-only storage adapters.
 
 Use this package in:
 
@@ -15,32 +15,35 @@ For Node servers, use [`@bsv/wallet-toolbox`](https://www.npmjs.com/package/@bsv
 
 ## Install
 
+Install the `@bsv/sdk` peer dependency alongside this package:
+
 ```bash
-npm install @bsv/wallet-toolbox-client
+npm install @bsv/wallet-toolbox-client @bsv/sdk
 ```
 
-Peer dependency: `@bsv/sdk`.
+## Package targets
+
+The package publishes:
+
+- an ESM browser/import target with source maps;
+- a CommonJS require target with source maps;
+- matching declarations for ESM and CommonJS;
+- explicit `browser`, `import`, and `require` export conditions.
+
+Use a current browser bundler such as Vite or esbuild. Node.js 22 or newer is required for the published tooling and contributor workflow; browser runtime support is determined by your application's target configuration.
 
-## Quick start
+## Remote storage example
 
 ```ts
-import {
-  Wallet,
-  WalletSigner,
-  WalletStorageManager,
-  StorageClient,
-  Services,
-} from '@bsv/wallet-toolbox-client'
+import { Wallet, WalletSigner, WalletStorageManager, StorageClient, Services } from '@bsv/wallet-toolbox-client'
 import { KeyDeriver, PrivateKey } from '@bsv/sdk'
 
 const chain = 'main'
 const keyDeriver = new KeyDeriver(new PrivateKey(privateKeyHex, 'hex'))
 
-// Remote storage over HTTP — no SQLite/MySQL in the browser bundle.
+// Remote storage over HTTPS — no SQLite/MySQL in the browser bundle.
 const storageManager = new WalletStorageManager(keyDeriver.identityKey)
-await storageManager.addWalletStorageProvider(
-  new StorageClient(keyDeriver, 'https://storage.example.com')
-)
+await storageManager.addWalletStorageProvider(new StorageClient(keyDeriver, 'https://storage.example.com'))
 await storageManager.makeAvailable()
 
 const services = new Services(chain)
@@ -50,7 +53,7 @@ const wallet = new Wallet(signer, services)
 // Use the BRC-100 interface as usual.
 const { tx } = await wallet.createAction({
   description: 'pay alice',
-  outputs: [{ satoshis: 1000, lockingScript: aliceP2PKH }],
+  outputs: [{ satoshis: 1000, lockingScript: aliceP2PKH }]
 })
 ```
 
@@ -69,7 +72,7 @@ const wallet = new WalletClient() // delegates to the user's installed wallet
 // ...or build your own with the toolbox classes above
 ```
 
-### Run an in-app embedded wallet against `IndexedDB`
+### Run an in-app embedded wallet against IndexedDB
 
 ```ts
 import { StorageIdb } from '@bsv/wallet-toolbox-client'
@@ -78,15 +81,33 @@ await storageManager.addWalletStorageProvider(new StorageIdb(...))
 
 ## What's excluded vs `@bsv/wallet-toolbox`
 
-| Excluded | Why |
-|----------|-----|
+| Excluded                      | Why                                     |
+| ----------------------------- | --------------------------------------- |
 | `StorageKnex` (SQLite, MySQL) | Pulls native bindings; not browser-safe |
-| Node-only filesystem helpers | Not available in browsers |
+| Node-only filesystem helpers  | Not available in browsers               |
 
-Everything else — `Wallet`, `WalletSigner`, `WalletStorageManager`, `StorageClient`, `StorageIdb`, `Services`, `Monitor`, `WalletPermissionsManager`, `WalletSettingsManager`, key management, MockChain — is identical to the full package.
+The browser entry includes `Wallet`, `WalletSigner`, `WalletStorageManager`, `StorageClient`, `StorageIdb`, `Services`, `Monitor`, `WalletPermissionsManager`, `WalletSettingsManager`, and related browser-safe APIs. It does not promise every full-package or test-only export.
 
 See the [`@bsv/wallet-toolbox`](https://www.npmjs.com/package/@bsv/wallet-toolbox) README for full documentation.
 
+## CORS, CSP, and public services
+
+This client does not impose an origin allowlist. A remote Storage service controls its own CORS policy and should remain reachable by its intended public web, WUI, extension, and mobile clients. Operators can keep public access enabled by default or configure an explicit allowlist when their deployment requires one; deployments should not assume a single calling domain.
+
+CSP is an application and deployment concern rather than a package-level access control. Add the service's HTTPS origin to the consuming application's `connect-src` policy. Keep authentication and authorization at the protocol/service layer instead of treating CORS as an authentication mechanism.
+
+## Contributor checks
+
+From the repository root, build the SDK and package before running the installed-consumer browser gate:
+
+```bash
+pnpm --filter @bsv/sdk build
+pnpm --filter @bsv/wallet-toolbox-client build
+pnpm --filter @bsv/wallet-toolbox-client test:browser
+```
+
+The gate installs the packed packages in a clean project, bundles them with Vite and esbuild, checks the public export and browser-only module contracts, validates source maps, and enforces compressed and uncompressed size budgets.
+
 ## License
 
-Open BSV License — see [LICENSE.txt](./LICENSE.txt).
+Open BSV License Version 6 — see [LICENSE.txt](./LICENSE.txt).