@bsv/wallet-toolbox 1.7.22 → 1.8.1

package/src/entropy/EntropyCollector.ts

@@ -0,0 +1,228 @@
+/**
+ * EntropyCollector
+ *
+ * Collects entropy from user interactions (mouse movements) and mixes it with
+ * cryptographically secure random numbers to generate high-quality random seeds
+ * for key generation.
+ *
+ * This provides defense-in-depth: even if the system's CSPRNG is compromised,
+ * the user-provided entropy adds unpredictability. Conversely, if the user's
+ * mouse movements are predictable, the CSPRNG ensures security.
+ */
+
+import { Random, Hash } from '@bsv/sdk'
+
+export interface EntropyCollectorConfig {
+  /** Target number of mouse samples to collect (default: 256) */
+  targetSamples?: number
+  /** Minimum time between samples in ms (default: 10) */
+  minSampleInterval?: number
+}
+
+export interface EntropyProgress {
+  /** Number of samples collected so far */
+  collected: number
+  /** Target number of samples */
+  target: number
+  /** Percentage complete (0-100) */
+  percent: number
+}
+
+/**
+ * Callback type for entropy collection progress updates
+ */
+export type EntropyProgressCallback = (progress: EntropyProgress) => void
+
+/**
+ * Collected entropy data before mixing
+ */
+interface RawEntropyData {
+  mousePositions: Array<{ x: number; y: number; time: number }>
+  timingDeltas: number[]
+}
+
+export class EntropyCollector {
+  private config: Required<EntropyCollectorConfig>
+  private rawEntropy: RawEntropyData = {
+    mousePositions: [],
+    timingDeltas: []
+  }
+  private lastSampleTime: number = 0
+
+  constructor(config: EntropyCollectorConfig = {}) {
+    this.config = {
+      targetSamples: config.targetSamples ?? 256,
+      minSampleInterval: config.minSampleInterval ?? 10
+    }
+  }
+
+  /**
+   * Reset collected entropy data
+   */
+  reset(): void {
+    this.rawEntropy = {
+      mousePositions: [],
+      timingDeltas: []
+    }
+    this.lastSampleTime = 0
+  }
+
+  /**
+   * Add a mouse movement sample
+   * Call this from a mousemove event handler
+   *
+   * @returns Progress information, or null if sample was rejected (too soon)
+   */
+  addMouseSample(x: number, y: number): EntropyProgress | null {
+    const now = performance.now()
+
+    // Rate limit samples to reduce correlation
+    if (now - this.lastSampleTime < this.config.minSampleInterval) {
+      return null
+    }
+
+    // Record timing delta (high precision timing adds entropy)
+    if (this.lastSampleTime > 0) {
+      this.rawEntropy.timingDeltas.push(now - this.lastSampleTime)
+    }
+    this.lastSampleTime = now
+
+    // Record position
+    this.rawEntropy.mousePositions.push({ x, y, time: now })
+
+    return this.getProgress()
+  }
+
+  /**
+   * Get current collection progress
+   */
+  getProgress(): EntropyProgress {
+    const collected = this.rawEntropy.mousePositions.length
+    return {
+      collected,
+      target: this.config.targetSamples,
+      percent: Math.min(100, Math.floor((collected / this.config.targetSamples) * 100))
+    }
+  }
+
+  /**
+   * Check if enough entropy has been collected
+   */
+  isComplete(): boolean {
+    return this.rawEntropy.mousePositions.length >= this.config.targetSamples
+  }
+
+  /**
+   * Extract entropy bytes from collected mouse data
+   * Uses SHA-256 to compress and whiten the data
+   */
+  private extractRawEntropy(): Uint8Array {
+    // Serialize all collected data
+    const dataPoints: number[] = []
+
+    // Add mouse positions
+    for (const pos of this.rawEntropy.mousePositions) {
+      // Use lower bits of coordinates (more random due to jitter)
+      dataPoints.push(pos.x & 0xff)
+      dataPoints.push(pos.y & 0xff)
+      // Include fractional timing (microsecond precision)
+      dataPoints.push(Math.floor(pos.time * 1000) & 0xff)
+      dataPoints.push(Math.floor(pos.time * 1000000) & 0xff)
+    }
+
+    // Add timing deltas (high entropy source)
+    for (const delta of this.rawEntropy.timingDeltas) {
+      // Timing deltas converted to bytes
+      dataPoints.push(Math.floor(delta * 1000) & 0xff)
+      dataPoints.push(Math.floor(delta * 1000000) & 0xff)
+    }
+
+    // Hash to compress and whiten the entropy
+    const hash = Hash.sha256(dataPoints)
+    return new Uint8Array(hash)
+  }
+
+  /**
+   * Mix user entropy with system CSPRNG for defense-in-depth
+   *
+   * @returns 32 bytes of high-quality random data suitable for key generation
+   */
+  mixWithCSPRNG(): Uint8Array {
+    const userEntropy = this.extractRawEntropy()
+    const systemEntropy = new Uint8Array(Random(32))
+
+    // XOR user entropy with system entropy
+    const mixed = new Uint8Array(32)
+    for (let i = 0; i < 32; i++) {
+      mixed[i] = userEntropy[i] ^ systemEntropy[i]
+    }
+
+    // Final hash to ensure uniform distribution
+    const final = Hash.sha256(Array.from(mixed))
+    return new Uint8Array(final)
+  }
+
+  /**
+   * Generate entropy with automatic CSPRNG fallback
+   *
+   * If not enough user entropy has been collected, supplements with CSPRNG.
+   * Always mixes with CSPRNG regardless.
+   *
+   * @returns 32 bytes suitable for private key generation
+   */
+  generateEntropy(): Uint8Array {
+    if (!this.isComplete()) {
+      console.warn(
+        `EntropyCollector: Only ${this.rawEntropy.mousePositions.length}/${this.config.targetSamples} ` +
+          `samples collected. Supplementing with additional CSPRNG entropy.`
+      )
+    }
+
+    return this.mixWithCSPRNG()
+  }
+
+  /**
+   * Convenience method for browser environments.
+   * Creates event listeners and resolves when enough entropy is collected.
+   *
+   * @param element The HTML element to listen on (default: document)
+   * @param onProgress Optional callback for progress updates
+   * @returns Promise that resolves with 32 bytes of entropy
+   */
+  async collectFromBrowser(element: EventTarget = document, onProgress?: EntropyProgressCallback): Promise<Uint8Array> {
+    return new Promise(resolve => {
+      const handler = (event: Event) => {
+        if (event instanceof MouseEvent) {
+          const progress = this.addMouseSample(event.clientX, event.clientY)
+          if (progress) {
+            onProgress?.(progress)
+
+            if (this.isComplete()) {
+              element.removeEventListener('mousemove', handler)
+              resolve(this.generateEntropy())
+            }
+          }
+        }
+      }
+
+      element.addEventListener('mousemove', handler)
+    })
+  }
+
+  /**
+   * Estimate the quality of collected entropy in bits
+   * This is a rough heuristic, not a cryptographic guarantee
+   */
+  estimateEntropyBits(): number {
+    const samples = this.rawEntropy.mousePositions.length
+
+    if (samples === 0) return 0
+
+    // Assume roughly 4-6 bits per mouse position (jitter in lower bits)
+    // Plus 2-4 bits from timing
+    const bitsPerSample = 6
+
+    // Cap at 256 bits (32 bytes) since that's our output size
+    return Math.min(256, samples * bitsPerSample)
+  }
+}

package/src/entropy/__tests/EntropyCollector.test.ts

@@ -0,0 +1,182 @@
+import { EntropyCollector } from '../EntropyCollector'
+
+describe('EntropyCollector', () => {
+  describe('Configuration', () => {
+    it('should use default configuration', () => {
+      const collector = new EntropyCollector()
+      const progress = collector.getProgress()
+
+      expect(progress.target).toBe(256)
+      expect(progress.collected).toBe(0)
+      expect(progress.percent).toBe(0)
+    })
+
+    it('should accept custom configuration', () => {
+      const collector = new EntropyCollector({
+        targetSamples: 100,
+        minSampleInterval: 20
+      })
+      const progress = collector.getProgress()
+
+      expect(progress.target).toBe(100)
+    })
+  })
+
+  describe('Sample Collection', () => {
+    it('should collect mouse samples', () => {
+      const collector = new EntropyCollector({ targetSamples: 10, minSampleInterval: 0 })
+
+      const progress = collector.addMouseSample(100, 200)
+
+      expect(progress).not.toBeNull()
+      expect(progress!.collected).toBe(1)
+    })
+
+    it('should reject samples that are too close together', () => {
+      const collector = new EntropyCollector({ targetSamples: 10, minSampleInterval: 1000 })
+
+      collector.addMouseSample(100, 200)
+      const secondProgress = collector.addMouseSample(101, 201)
+
+      expect(secondProgress).toBeNull()
+    })
+
+    it('should track progress percentage', () => {
+      const collector = new EntropyCollector({ targetSamples: 10, minSampleInterval: 0 })
+
+      for (let i = 0; i < 5; i++) {
+        collector.addMouseSample(i * 10, i * 20)
+      }
+
+      const progress = collector.getProgress()
+      expect(progress.percent).toBe(50)
+    })
+
+    it('should cap percent at 100', () => {
+      const collector = new EntropyCollector({ targetSamples: 5, minSampleInterval: 0 })
+
+      for (let i = 0; i < 10; i++) {
+        collector.addMouseSample(i * 10, i * 20)
+      }
+
+      const progress = collector.getProgress()
+      expect(progress.percent).toBe(100)
+    })
+  })
+
+  describe('Completion', () => {
+    it('should report incomplete when not enough samples', () => {
+      const collector = new EntropyCollector({ targetSamples: 100, minSampleInterval: 0 })
+
+      for (let i = 0; i < 50; i++) {
+        collector.addMouseSample(i, i)
+      }
+
+      expect(collector.isComplete()).toBe(false)
+    })
+
+    it('should report complete when enough samples collected', () => {
+      const collector = new EntropyCollector({ targetSamples: 10, minSampleInterval: 0 })
+
+      for (let i = 0; i < 10; i++) {
+        collector.addMouseSample(i * 5, i * 10)
+      }
+
+      expect(collector.isComplete()).toBe(true)
+    })
+  })
+
+  describe('Reset', () => {
+    it('should reset collected samples', () => {
+      const collector = new EntropyCollector({ targetSamples: 10, minSampleInterval: 0 })
+
+      for (let i = 0; i < 5; i++) {
+        collector.addMouseSample(i, i)
+      }
+
+      expect(collector.getProgress().collected).toBe(5)
+
+      collector.reset()
+
+      expect(collector.getProgress().collected).toBe(0)
+      expect(collector.isComplete()).toBe(false)
+    })
+  })
+
+  describe('Entropy Generation', () => {
+    it('should generate 32 bytes of entropy', () => {
+      const collector = new EntropyCollector({ targetSamples: 10, minSampleInterval: 0 })
+
+      for (let i = 0; i < 10; i++) {
+        collector.addMouseSample(Math.random() * 1000, Math.random() * 1000)
+      }
+
+      const entropy = collector.generateEntropy()
+
+      expect(entropy).toBeInstanceOf(Uint8Array)
+      expect(entropy.length).toBe(32)
+    })
+
+    it('should generate entropy even with insufficient samples (with warning)', () => {
+      const collector = new EntropyCollector({ targetSamples: 100, minSampleInterval: 0 })
+
+      // Only add a few samples
+      for (let i = 0; i < 5; i++) {
+        collector.addMouseSample(i, i)
+      }
+
+      const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
+
+      const entropy = collector.generateEntropy()
+
+      expect(entropy.length).toBe(32)
+      expect(consoleSpy).toHaveBeenCalled()
+
+      consoleSpy.mockRestore()
+    })
+
+    it('should generate different entropy on each call (due to CSPRNG mixing)', () => {
+      const collector = new EntropyCollector({ targetSamples: 10, minSampleInterval: 0 })
+
+      for (let i = 0; i < 10; i++) {
+        collector.addMouseSample(i, i)
+      }
+
+      const entropy1 = collector.generateEntropy()
+      const entropy2 = collector.generateEntropy()
+
+      // They should be different due to CSPRNG mixing
+      expect(Buffer.from(entropy1).toString('hex')).not.toBe(Buffer.from(entropy2).toString('hex'))
+    })
+  })
+
+  describe('Entropy Estimation', () => {
+    it('should estimate 0 bits with no samples', () => {
+      const collector = new EntropyCollector()
+      expect(collector.estimateEntropyBits()).toBe(0)
+    })
+
+    it('should estimate entropy based on sample count', () => {
+      const collector = new EntropyCollector({ targetSamples: 100, minSampleInterval: 0 })
+
+      for (let i = 0; i < 20; i++) {
+        collector.addMouseSample(i, i)
+      }
+
+      const bits = collector.estimateEntropyBits()
+      expect(bits).toBeGreaterThan(0)
+      expect(bits).toBeLessThanOrEqual(256) // Capped at 256
+    })
+
+    it('should cap entropy estimate at 256 bits', () => {
+      const collector = new EntropyCollector({ targetSamples: 1000, minSampleInterval: 0 })
+
+      for (let i = 0; i < 500; i++) {
+        collector.addMouseSample(i, i)
+      }
+
+      const bits = collector.estimateEntropyBits()
+      expect(bits).toBe(256)
+    })
+  })
+})

package/src/index.all.ts

@@ -25,3 +25,5 @@ export * from './Wallet'
 export * from './WalletLogger'
 export * from './WalletAuthenticationManager'
 export * from './WalletPermissionsManager'
+export * from './ShamirWalletManager'
+export * from './entropy/EntropyCollector'

package/src/sdk/WalletServices.interfaces.ts

@@ -9,7 +9,6 @@ import {
 import { Chain, ReqHistoryNote } from './types'
 import { WalletError } from './WalletError'
 import { TableOutput } from '../storage/schema/tables/TableOutput'
-import { ChaintracksServiceClient } from '../services/chaintracker/chaintracks/ChaintracksServiceClient'
 import { ChaintracksClientApi } from '../services/chaintracker/chaintracks/Api/ChaintracksClientApi'
 /**
  * Defines standard interfaces to access functionality implemented by external transaction processing services.

package/src/services/chaintracker/chaintracks/Storage/ChaintracksStorageBase.ts

@@ -365,7 +365,10 @@ export abstract class ChaintracksStorageBase implements ChaintracksStorageQueryA
   private async addLiveHeadersToBulk(liveHeaders: LiveBlockHeader[]) {
     if (liveHeaders.length === 0) return
     const lastChainWork = liveHeaders.slice(-1)[0].chainWork
-    await this.bulkManager.mergeIncrementalBlockHeaders(liveHeaders, lastChainWork)
+    const firstHeader = liveHeaders[0]
+    const previousWork = subWork(firstHeader.chainWork, convertBitsToWork(liveHeaders[0].bits))
+    const incrementalWork = subWork(lastChainWork, previousWork)
+    await this.bulkManager.mergeIncrementalBlockHeaders(liveHeaders, incrementalWork)
   }
 }
 

package/src/wab-client/WABClient.ts

@@ -91,4 +91,139 @@ export class WABClient {
     })
     return res.json()
   }
+
+  // ============================================================
+  // Shamir Share Management (2-of-3 Key Recovery System)
+  // ============================================================
+
+  /**
+   * Start OTP verification for share operations
+   * This initiates the auth flow (e.g., sends SMS code via Twilio)
+   *
+   * @param methodType The auth method type (e.g., "TwilioPhone", "DevConsole")
+   * @param userIdHash SHA256 hash of the user's identity key
+   * @param payload Auth method specific data (e.g., { phoneNumber: "+1..." })
+   */
+  public async startShareAuth(
+    methodType: string,
+    userIdHash: string,
+    payload: any
+  ): Promise<{ success: boolean; message: string }> {
+    const res = await fetch(`${this.serverUrl}/auth/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        methodType,
+        presentationKey: userIdHash, // Reuse existing auth flow with userIdHash
+        payload
+      })
+    })
+    return res.json()
+  }
+
+  /**
+   * Store a Shamir share (Share B) on the server
+   * Requires prior OTP verification via startShareAuth
+   *
+   * @param methodType The auth method type used for verification
+   * @param payload Contains the OTP code and auth method specific data
+   * @param shareB The Shamir share to store (format: x.y.threshold.integrity)
+   * @param userIdHash SHA256 hash of the user's identity key
+   */
+  public async storeShare(
+    methodType: string,
+    payload: any,
+    shareB: string,
+    userIdHash: string
+  ): Promise<{ success: boolean; message: string; userId?: number }> {
+    const res = await fetch(`${this.serverUrl}/share/store`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        methodType,
+        payload,
+        shareB,
+        userIdHash
+      })
+    })
+    return res.json()
+  }
+
+  /**
+   * Retrieve a Shamir share (Share B) from the server
+   * Requires OTP verification
+   *
+   * @param methodType The auth method type used for verification
+   * @param payload Contains the OTP code and auth method specific data
+   * @param userIdHash SHA256 hash of the user's identity key
+   */
+  public async retrieveShare(
+    methodType: string,
+    payload: any,
+    userIdHash: string
+  ): Promise<{ success: boolean; shareB?: string; message: string }> {
+    const res = await fetch(`${this.serverUrl}/share/retrieve`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        methodType,
+        payload,
+        userIdHash
+      })
+    })
+    return res.json()
+  }
+
+  /**
+   * Update a Shamir share (for key rotation)
+   * Requires OTP verification
+   *
+   * @param methodType The auth method type used for verification
+   * @param payload Contains the OTP code and auth method specific data
+   * @param userIdHash SHA256 hash of the user's identity key
+   * @param newShareB The new Shamir share to store
+   */
+  public async updateShare(
+    methodType: string,
+    payload: any,
+    userIdHash: string,
+    newShareB: string
+  ): Promise<{ success: boolean; message: string; shareVersion?: number }> {
+    const res = await fetch(`${this.serverUrl}/share/update`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        methodType,
+        payload,
+        userIdHash,
+        newShareB
+      })
+    })
+    return res.json()
+  }
+
+  /**
+   * Delete a Shamir user's account and stored share
+   * Requires OTP verification
+   *
+   * @param methodType The auth method type used for verification
+   * @param payload Contains the OTP code and auth method specific data
+   * @param userIdHash SHA256 hash of the user's identity key
+   */
+  public async deleteShamirUser(
+    methodType: string,
+    payload: any,
+    userIdHash: string
+  ): Promise<{ success: boolean; message: string }> {
+    const res = await fetch(`${this.serverUrl}/share/delete`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        methodType,
+        payload,
+        userIdHash
+      })
+    })
+    return res.json()
+  }
 }