@bsv/wallet-toolbox 1.7.22 → 1.8.2

package/CHANGELOG.md

@@ -4,6 +4,14 @@ This document captures the history of significant changes to the wallet-toolbox
 The git commit history contains the details but is unable to draw
 attention to changes that materially alter behavior or extend functionality.
 
+## wallet-toolbox 1.7.24
+
+- Add full P-label (permissioned label) support per BRC-111 specification.
+- Implement P-label format validation: p <moduleId> <payload> with strict parsing rules.
+- Updated createAction, internalizeAction, and listActions to handle P-labels with permission module delegation.
+- Add comprehensive test coverage for P-label delegation, multi-module chaining, and format validation.
+- Added small fix to reject pending promises on grantGroupedPermission error.
+
 ## wallet-toolbox 1.7.17
 
 - Fix push.yaml to sync versions, correct root package contents (no mobile), and publish client and mobile

package/docs/README.md

@@ -9,6 +9,7 @@ The documentation is split into various pages, each covering a set of related fu
 - [Storage](./storage.md) — Wallet data persistent storage classes and related APIs.
 - [Services](./services.md) — Support for abstracted external network services.
 - [Monitor](./monitor.md) — Background task manager for wallet action validation and processing.
+- [WAB Shamir](./wab-shamir.md) — Shamir 2-of-3 key recovery system with entropy collection and WAB server integration.
 
 ## Open API
 

package/docs/client.md

@@ -14069,6 +14069,29 @@ export class WABClient {
     public async unlinkMethod(presentationKey: string, authMethodId: number) 
     public async requestFaucet(presentationKey: string) 
     public async deleteUser(presentationKey: string) 
+    public async startShareAuth(methodType: string, userIdHash: string, payload: any): Promise<{
+        success: boolean;
+        message: string;
+    }> 
+    public async storeShare(methodType: string, payload: any, shareB: string, userIdHash: string): Promise<{
+        success: boolean;
+        message: string;
+        userId?: number;
+    }> 
+    public async retrieveShare(methodType: string, payload: any, userIdHash: string): Promise<{
+        success: boolean;
+        shareB?: string;
+        message: string;
+    }> 
+    public async updateShare(methodType: string, payload: any, userIdHash: string, newShareB: string): Promise<{
+        success: boolean;
+        message: string;
+        shareVersion?: number;
+    }> 
+    public async deleteShamirUser(methodType: string, payload: any, userIdHash: string): Promise<{
+        success: boolean;
+        message: string;
+    }> 
 }
 ```
 
@@ -14083,6 +14106,27 @@ public async completeAuthMethod(authMethod: AuthMethodInteractor, presentationKe
 ```
 See also: [AuthMethodInteractor](./client.md#class-authmethodinteractor)
 
+###### Method deleteShamirUser
+
+Delete a Shamir user's account and stored share
+Requires OTP verification
+
+```ts
+public async deleteShamirUser(methodType: string, payload: any, userIdHash: string): Promise<{
+    success: boolean;
+    message: string;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type used for verification
++ **payload**
+  + Contains the OTP code and auth method specific data
++ **userIdHash**
+  + SHA256 hash of the user's identity key
+
 ###### Method deleteUser
 
 Delete user
@@ -14123,6 +14167,28 @@ Request faucet
 public async requestFaucet(presentationKey: string) 
 ```
 
+###### Method retrieveShare
+
+Retrieve a Shamir share (Share B) from the server
+Requires OTP verification
+
+```ts
+public async retrieveShare(methodType: string, payload: any, userIdHash: string): Promise<{
+    success: boolean;
+    shareB?: string;
+    message: string;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type used for verification
++ **payload**
+  + Contains the OTP code and auth method specific data
++ **userIdHash**
+  + SHA256 hash of the user's identity key
+
 ###### Method startAuthMethod
 
 Start an Auth Method flow
@@ -14132,6 +14198,51 @@ public async startAuthMethod(authMethod: AuthMethodInteractor, presentationKey:
 ```
 See also: [AuthMethodInteractor](./client.md#class-authmethodinteractor)
 
+###### Method startShareAuth
+
+Start OTP verification for share operations
+This initiates the auth flow (e.g., sends SMS code via Twilio)
+
+```ts
+public async startShareAuth(methodType: string, userIdHash: string, payload: any): Promise<{
+    success: boolean;
+    message: string;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type (e.g., "TwilioPhone", "DevConsole")
++ **userIdHash**
+  + SHA256 hash of the user's identity key
++ **payload**
+  + Auth method specific data (e.g., { phoneNumber: "+1..." })
+
+###### Method storeShare
+
+Store a Shamir share (Share B) on the server
+Requires prior OTP verification via startShareAuth
+
+```ts
+public async storeShare(methodType: string, payload: any, shareB: string, userIdHash: string): Promise<{
+    success: boolean;
+    message: string;
+    userId?: number;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type used for verification
++ **payload**
+  + Contains the OTP code and auth method specific data
++ **shareB**
+  + The Shamir share to store (format: x.y.threshold.integrity)
++ **userIdHash**
+  + SHA256 hash of the user's identity key
+
 ###### Method unlinkMethod
 
 Unlink a given Auth Method by ID
@@ -14140,6 +14251,30 @@ Unlink a given Auth Method by ID
 public async unlinkMethod(presentationKey: string, authMethodId: number) 
 ```
 
+###### Method updateShare
+
+Update a Shamir share (for key rotation)
+Requires OTP verification
+
+```ts
+public async updateShare(methodType: string, payload: any, userIdHash: string, newShareB: string): Promise<{
+    success: boolean;
+    message: string;
+    shareVersion?: number;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type used for verification
++ **payload**
+  + Contains the OTP code and auth method specific data
++ **userIdHash**
+  + SHA256 hash of the user's identity key
++ **newShareB**
+  + The new Shamir share to store
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---

package/docs/wab-shamir.md

@@ -0,0 +1,311 @@
+# WAB Shamir Key Recovery
+
+This guide covers the Shamir Secret Sharing key recovery system, which provides secure wallet backup and recovery using a configurable threshold scheme.
+
+## Overview
+
+The Shamir system splits your wallet's root private key into multiple shares. A configurable threshold of shares can reconstruct the key:
+
+- **Server share**: Stored on WAB server, released only after OTP verification
+- **User shares**: Application decides how to store (print, password manager, hardware device, etc.)
+
+**Default configuration (2-of-3):**
+- 3 total shares, 2 required to reconstruct
+- Server holds 1 share, user receives 2 shares
+- Any 2 shares can recover the key
+
+**Example configurations:**
+
+| Threshold | Total | Server | User Shares | Use Case |
+|-----------|-------|--------|-------------|----------|
+| 2 | 3 | 1 | 2 | Standard (default) |
+| 2 | 4 | 1 | 3 | Extra redundancy |
+| 3 | 5 | 1 | 4 | High security |
+| 3 | 4 | 1 | 3 | Balanced security |
+
+**Important constraint:** User must always have at least `threshold` shares so they can recover independently without the server. This prevents the WAB from becoming a custodian of user funds. For example, 2-of-2 is not allowed because the user would only have 1 share and could not recover without server cooperation.
+
+The WAB server always stores exactly one share and cannot reconstruct the key alone.
+
+## Generating a Secure Key with Entropy Collection
+
+For maximum security, keys are generated using mouse movement entropy mixed with the system's cryptographically secure random number generator (CSPRNG).
+
+```ts
+import { EntropyCollector } from '@bsv/wallet-toolbox'
+
+// Create collector (default: 256 samples)
+const collector = new EntropyCollector({
+    targetSamples: 256,
+    minSampleInterval: 10 // ms between samples
+})
+
+// Option 1: Manual collection from mousemove events
+document.addEventListener('mousemove', (event) => {
+    const progress = collector.addMouseSample(event.clientX, event.clientY)
+    if (progress) {
+        console.log(`Entropy: ${progress.percent}% (${progress.collected}/${progress.target})`)
+    }
+})
+
+// Check when complete
+if (collector.isComplete()) {
+    const entropy = collector.generateEntropy() // 32 bytes
+}
+
+// Option 2: Automatic browser collection with progress callback
+const entropy = await collector.collectFromBrowser(document, (progress) => {
+    updateProgressBar(progress.percent)
+})
+```
+
+The `generateEntropy()` method:
+1. Extracts raw entropy from mouse positions and timing
+2. Hashes it with SHA-256 to whiten the data
+3. XORs with `crypto.getRandomValues()` output
+4. Final SHA-256 hash ensures uniform distribution
+
+## Using ShamirWalletManager
+
+The `ShamirWalletManager` class handles the complete wallet lifecycle with Shamir shares.
+
+### Configuration
+
+```ts
+import { ShamirWalletManager, Setup, PrivateKey, PrivilegedKeyManager } from '@bsv/wallet-toolbox'
+
+const manager = new ShamirWalletManager({
+    wabServerUrl: 'https://your-wab-server.com',
+    authMethodType: 'TwilioPhone', // or 'DevConsole' for development
+
+    // Optional: customize threshold scheme (defaults to 2-of-3)
+    threshold: 2,    // shares needed to reconstruct (min: 2)
+    totalShares: 3,  // total shares generated (min: 3, must be >= threshold + 1)
+
+    walletBuilder: async (privateKey, privilegedKeyManager) => {
+        const { wallet } = await Setup.createWalletSQLite({
+            filePath: './wallet.sqlite',
+            databaseName: 'myWallet',
+            chain: 'main',
+            rootKeyHex: privateKey.toHex(),
+            privilegedKeyManager
+        })
+        return wallet
+    }
+})
+
+// Check configuration
+console.log(`Using ${manager.getThreshold()}-of-${manager.getTotalShares()} scheme`)
+```
+
+### Creating a New Wallet
+
+```ts
+// 1. Collect entropy (show user a "move your mouse" UI)
+await manager.collectEntropyFromBrowser(document, (progress) => {
+    document.getElementById('progress').textContent = `${progress.percent}%`
+})
+
+// 2. Start OTP verification (user receives SMS)
+const wabClient = new WABClient('https://your-wab-server.com')
+await wabClient.startShareAuth('TwilioPhone', userIdHash, {
+    phoneNumber: '+1234567890'
+})
+
+// 3. User enters OTP code, then create wallet
+const result = await manager.createNewWallet(
+    { phoneNumber: '+1234567890', otp: '123456' },
+    async (userShares, threshold, totalShares) => {
+        // Application decides how to handle user shares
+        // For 2-of-3: userShares has 2 shares
+        console.log(`Save these ${userShares.length} shares (${threshold}-of-${totalShares} scheme)`)
+
+        // Example: first share for printing, second for password manager
+        await showPrintableBackup(userShares[0])
+        await showCopyableText(userShares[1])
+
+        return await confirmUserSavedShares()
+    }
+)
+
+console.log('User ID Hash:', result.userIdHash)
+console.log('User Shares:', result.userShares)
+console.log(`Scheme: ${result.threshold}-of-${result.totalShares}`)
+
+// 4. Build and use the wallet
+const wallet = await manager.buildWallet()
+```
+
+### Recovery with Server Share
+
+When the user has enough shares but needs the server share to meet threshold:
+
+```ts
+const manager = new ShamirWalletManager({ /* config */ })
+
+// User provides their userIdHash
+manager.setUserIdHash(savedUserIdHash)
+
+// Start OTP to retrieve server share
+await manager.startOTPVerification({ phoneNumber: '+1234567890' })
+
+// Recover with user shares (need threshold-1 shares)
+// For 2-of-3: need 1 user share + server share
+const privateKey = await manager.recoverWithServerShare(
+    [userShare1], // Array of user-held shares
+    { phoneNumber: '+1234567890', otp: '123456' }
+)
+
+const wallet = await manager.buildWallet()
+```
+
+### Recovery with User Shares Only (Offline)
+
+When the user has enough shares to meet threshold without the server:
+
+```ts
+const manager = new ShamirWalletManager({ /* config */ })
+
+// Recover using user-held shares (need at least threshold shares)
+// For 2-of-3: need 2 user shares
+const privateKey = await manager.recoverWithUserShares([userShare1, userShare2])
+
+const wallet = await manager.buildWallet()
+```
+
+## Using WABClient Directly
+
+For lower-level control, use `WABClient` directly:
+
+```ts
+import { WABClient } from '@bsv/wallet-toolbox'
+
+const client = new WABClient('https://your-wab-server.com')
+
+// Start OTP verification
+await client.startShareAuth('TwilioPhone', userIdHash, {
+    phoneNumber: '+1234567890'
+})
+
+// Store the server share (after OTP verification)
+const storeResult = await client.storeShare(
+    'TwilioPhone',
+    { phoneNumber: '+1234567890', otp: '123456' },
+    serverShare, // The share to store (format: x.y.threshold.integrity)
+    userIdHash
+)
+
+// Retrieve the server share (requires OTP)
+const retrieveResult = await client.retrieveShare(
+    'TwilioPhone',
+    { phoneNumber: '+1234567890', otp: '654321' },
+    userIdHash
+)
+console.log('Retrieved server share:', retrieveResult.shareB)
+
+// Update share (for key rotation)
+await client.updateShare(
+    'TwilioPhone',
+    { phoneNumber: '+1234567890', otp: '111222' },
+    userIdHash,
+    newServerShare
+)
+
+// Delete account and stored share
+await client.deleteShamirUser(
+    'TwilioPhone',
+    { phoneNumber: '+1234567890', otp: '333444' },
+    userIdHash
+)
+```
+
+## Key Rotation
+
+To rotate keys (generate new shares while maintaining access):
+
+```ts
+// Collect fresh entropy
+manager.resetEntropy()
+await manager.collectEntropyFromBrowser(document, onProgress)
+
+// Rotate keys (requires OTP verification)
+const newResult = await manager.rotateKeys(
+    { phoneNumber: '+1234567890', otp: '123456' },
+    async (userShares, threshold, totalShares) => {
+        console.log(`Save these ${userShares.length} NEW shares`)
+        // User must save all new shares
+        return await confirmUserSavedShares()
+    }
+)
+
+// Server share is automatically updated
+// User must save new user shares
+```
+
+## Account Deletion
+
+To delete a Shamir account and its stored share:
+
+```ts
+// Requires OTP verification
+await manager.deleteAccount({
+    phoneNumber: '+1234567890',
+    otp: '123456'
+})
+// WARNING: Server share is permanently deleted
+// User needs enough remaining shares to meet threshold
+```
+
+## Share Format
+
+Shamir shares use the format: `x.y.threshold.integrity`
+
+- **x**: Share index (1, 2, 3, ...)
+- **y**: Share data (Base58 encoded)
+- **threshold**: Number of shares required (e.g., 2)
+- **integrity**: Checksum for validation
+
+Example share:
+```
+1.7KvWLhJ3rQ9FnBZxYmUdNpTsR6CwEiAoH8bVfGjDkM2.2.5XyZ
+```
+
+## Security Considerations
+
+1. **Share Storage**: Store user shares in separate, secure locations
+2. **Threshold Selection**: Higher threshold = more security but less convenience
+3. **OTP Security**: Consider SIM-swap risks with SMS; email may be safer for some users
+4. **Entropy Quality**: Always collect full entropy before key generation
+5. **User ID Hash**: Store separately - it identifies your account but cannot recover keys
+
+### Recommended Share Storage by Scheme
+
+**2-of-3 (default):**
+- Share 1: Print and store in safe/safety deposit box
+- Share 2: Save in password manager
+
+**3-of-5 (high security):**
+- Share 1: Print and store in safe
+- Share 2: Save in password manager
+- Share 3: Store on hardware device (USB)
+- Share 4: Give to trusted family member
+
+## Error Handling
+
+```ts
+try {
+    await manager.recoverWithServerShare(userShares, authPayload)
+} catch (error) {
+    if (error.message.includes('Rate limited')) {
+        // Too many attempts - wait and retry
+    } else if (error.message.includes('OTP verification failed')) {
+        // Wrong code - let user retry
+    } else if (error.message.includes('integrity check failed')) {
+        // Shares don't match - wrong share or corrupted
+    } else if (error.message.includes('Need at least')) {
+        // Not enough shares provided
+    }
+}
+```
+
+[Return to Documentation](./README.md)

package/docs/wallet.md

@@ -14068,6 +14068,29 @@ export class WABClient {
     public async unlinkMethod(presentationKey: string, authMethodId: number) 
     public async requestFaucet(presentationKey: string) 
     public async deleteUser(presentationKey: string) 
+    public async startShareAuth(methodType: string, userIdHash: string, payload: any): Promise<{
+        success: boolean;
+        message: string;
+    }> 
+    public async storeShare(methodType: string, payload: any, shareB: string, userIdHash: string): Promise<{
+        success: boolean;
+        message: string;
+        userId?: number;
+    }> 
+    public async retrieveShare(methodType: string, payload: any, userIdHash: string): Promise<{
+        success: boolean;
+        shareB?: string;
+        message: string;
+    }> 
+    public async updateShare(methodType: string, payload: any, userIdHash: string, newShareB: string): Promise<{
+        success: boolean;
+        message: string;
+        shareVersion?: number;
+    }> 
+    public async deleteShamirUser(methodType: string, payload: any, userIdHash: string): Promise<{
+        success: boolean;
+        message: string;
+    }> 
 }
 ```
 
@@ -14082,6 +14105,27 @@ public async completeAuthMethod(authMethod: AuthMethodInteractor, presentationKe
 ```
 See also: [AuthMethodInteractor](./client.md#class-authmethodinteractor)
 
+###### Method deleteShamirUser
+
+Delete a Shamir user's account and stored share
+Requires OTP verification
+
+```ts
+public async deleteShamirUser(methodType: string, payload: any, userIdHash: string): Promise<{
+    success: boolean;
+    message: string;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type used for verification
++ **payload**
+  + Contains the OTP code and auth method specific data
++ **userIdHash**
+  + SHA256 hash of the user's identity key
+
 ###### Method deleteUser
 
 Delete user
@@ -14122,6 +14166,28 @@ Request faucet
 public async requestFaucet(presentationKey: string) 
 ```
 
+###### Method retrieveShare
+
+Retrieve a Shamir share (Share B) from the server
+Requires OTP verification
+
+```ts
+public async retrieveShare(methodType: string, payload: any, userIdHash: string): Promise<{
+    success: boolean;
+    shareB?: string;
+    message: string;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type used for verification
++ **payload**
+  + Contains the OTP code and auth method specific data
++ **userIdHash**
+  + SHA256 hash of the user's identity key
+
 ###### Method startAuthMethod
 
 Start an Auth Method flow
@@ -14131,6 +14197,51 @@ public async startAuthMethod(authMethod: AuthMethodInteractor, presentationKey:
 ```
 See also: [AuthMethodInteractor](./client.md#class-authmethodinteractor)
 
+###### Method startShareAuth
+
+Start OTP verification for share operations
+This initiates the auth flow (e.g., sends SMS code via Twilio)
+
+```ts
+public async startShareAuth(methodType: string, userIdHash: string, payload: any): Promise<{
+    success: boolean;
+    message: string;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type (e.g., "TwilioPhone", "DevConsole")
++ **userIdHash**
+  + SHA256 hash of the user's identity key
++ **payload**
+  + Auth method specific data (e.g., { phoneNumber: "+1..." })
+
+###### Method storeShare
+
+Store a Shamir share (Share B) on the server
+Requires prior OTP verification via startShareAuth
+
+```ts
+public async storeShare(methodType: string, payload: any, shareB: string, userIdHash: string): Promise<{
+    success: boolean;
+    message: string;
+    userId?: number;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type used for verification
++ **payload**
+  + Contains the OTP code and auth method specific data
++ **shareB**
+  + The Shamir share to store (format: x.y.threshold.integrity)
++ **userIdHash**
+  + SHA256 hash of the user's identity key
+
 ###### Method unlinkMethod
 
 Unlink a given Auth Method by ID
@@ -14139,6 +14250,30 @@ Unlink a given Auth Method by ID
 public async unlinkMethod(presentationKey: string, authMethodId: number) 
 ```
 
+###### Method updateShare
+
+Update a Shamir share (for key rotation)
+Requires OTP verification
+
+```ts
+public async updateShare(methodType: string, payload: any, userIdHash: string, newShareB: string): Promise<{
+    success: boolean;
+    message: string;
+    shareVersion?: number;
+}> 
+```
+
+Argument Details
+
++ **methodType**
+  + The auth method type used for verification
++ **payload**
+  + Contains the OTP code and auth method specific data
++ **userIdHash**
+  + SHA256 hash of the user's identity key
++ **newShareB**
+  + The new Shamir share to store
+
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Variables](#variables)
 
 ---