@bsv/wallet-toolbox 1.1.0

package/src/sdk/PrivilegedKeyManager.ts

@@ -0,0 +1,402 @@
+import {
+  Random,
+  Utils,
+  PrivateKey,
+  CreateHmacArgs,
+  CreateHmacResult,
+  CreateSignatureArgs,
+  CreateSignatureResult,
+  GetPublicKeyArgs,
+  ProtoWallet,
+  PubKeyHex,
+  RevealCounterpartyKeyLinkageArgs,
+  RevealCounterpartyKeyLinkageResult,
+  RevealSpecificKeyLinkageArgs,
+  RevealSpecificKeyLinkageResult,
+  VerifyHmacArgs,
+  VerifyHmacResult,
+  VerifySignatureArgs,
+  VerifySignatureResult,
+  WalletDecryptArgs,
+  WalletDecryptResult,
+  WalletEncryptArgs,
+  WalletEncryptResult
+} from '@bsv/sdk'
+
+/**
+ * PrivilegedKeyManager
+ *
+ * This class manages a privileged (i.e., very sensitive) private key, obtained from
+ * an external function (`keyGetter`), which might be backed by HSMs, secure enclaves,
+ * or other secure storage. The manager retains the key in memory only for a limited
+ * duration (`retentionPeriod`), uses XOR-based chunk-splitting obfuscation, and
+ * includes decoy data to raise the difficulty of discovering the real key in memory.
+ *
+ * IMPORTANT: While these measures raise the bar for attackers, JavaScript environments
+ * do not provide perfect in-memory secrecy.
+ */
+export class PrivilegedKeyManager {
+  /**
+   * Function that will retrieve the PrivateKey from a secure environment,
+   * e.g., an HSM or secure enclave. The reason for key usage is passed in
+   * to help with user consent, auditing, and access policy checks.
+   */
+  private keyGetter: (reason: string) => Promise<PrivateKey>
+
+  /**
+   * Time (in ms) for which the obfuscated key remains in memory
+   * before being automatically destroyed.
+   */
+  private retentionPeriod: number
+
+  /**
+   * A list of dynamically generated property names used to store
+   * real key chunks (XORed with random pads).
+   */
+  private chunkPropNames: string[] = []
+
+  /**
+   * A list of dynamically generated property names used to store
+   * the random pads that correspond to the real key chunks.
+   */
+  private chunkPadPropNames: string[] = []
+
+  /**
+   * A list of decoy property names that will be removed
+   * when the real key is destroyed.
+   */
+  private decoyPropNamesDestroy: string[] = []
+
+  /**
+   * A list of decoy property names that remain in memory
+   * even after the real key is destroyed (just to cause confusion).
+   */
+  private decoyPropNamesRemain: string[] = []
+
+  /**
+   * Handle to the timer that will remove the key from memory
+   * after the retention period. If the key is refreshed again
+   * within that period, the timer is cleared and re-set.
+   */
+  private destroyTimer: any | undefined
+
+  /**
+   * Number of chunks to split the 32-byte key into.
+   * Adjust to increase or decrease obfuscation complexity.
+   */
+  private readonly CHUNK_COUNT = 4
+
+  /**
+   * @param keyGetter - Asynchronous function that retrieves the PrivateKey from a secure environment.
+   * @param retentionPeriod - Time in milliseconds to retain the obfuscated key in memory before zeroizing.
+   */
+  constructor(
+    keyGetter: (reason: string) => Promise<PrivateKey>,
+    retentionPeriod = 120_000
+  ) {
+    this.keyGetter = keyGetter
+    this.retentionPeriod = retentionPeriod
+
+    // Initialize some random decoy properties that always remain:
+    for (let i = 0; i < 2; i++) {
+      const propName = this.generateRandomPropName()
+      // Store random garbage to cause confusion
+      ;(this as any)[propName] = Uint8Array.from(Random(16))
+      this.decoyPropNamesRemain.push(propName)
+    }
+  }
+
+  /**
+   * Safely destroys the in-memory obfuscated key material by zeroizing
+   * and deleting related fields. Also destroys some (but not all) decoy
+   * properties to further confuse an attacker.
+   */
+  destroyKey(): void {
+    try {
+      // Zero out real chunk data
+      for (const name of this.chunkPropNames) {
+        const data: Uint8Array | undefined = (this as any)[name]
+        if (data) {
+          data.fill(0)
+        }
+        delete (this as any)[name]
+      }
+      for (const name of this.chunkPadPropNames) {
+        const data: Uint8Array | undefined = (this as any)[name]
+        if (data) {
+          data.fill(0)
+        }
+        delete (this as any)[name]
+      }
+
+      // Destroy some decoys
+      for (const name of this.decoyPropNamesDestroy) {
+        const data: Uint8Array | undefined = (this as any)[name]
+        if (data) {
+          data.fill(0)
+        }
+        delete (this as any)[name]
+      }
+
+      // Clear arrays of property names
+      this.chunkPropNames = []
+      this.chunkPadPropNames = []
+      this.decoyPropNamesDestroy = []
+    } catch (_) {
+      // Swallow any errors in the destruction process
+    } finally {
+      if (this.destroyTimer) {
+        clearTimeout(this.destroyTimer)
+        this.destroyTimer = undefined
+      }
+    }
+  }
+
+  /**
+   * Re/sets the destruction timer that removes the key from memory
+   * after `retentionPeriod` ms. If a timer is already running, it
+   * is cleared and re-set. This ensures the key remains in memory
+   * for exactly the desired window after its most recent acquisition.
+   */
+  private scheduleKeyDestruction(): void {
+    if (this.destroyTimer) {
+      // TODO: Consider a constructor flag to avoid clearing timers for higher security
+      clearTimeout(this.destroyTimer)
+    }
+    this.destroyTimer = setTimeout(() => {
+      this.destroyKey()
+    }, this.retentionPeriod)
+  }
+
+  /**
+   * XOR-based obfuscation on a per-chunk basis.
+   * This function takes two equal-length byte arrays
+   * and returns the XOR combination.
+   */
+  private xorBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+    const out = new Uint8Array(a.length)
+    for (let i = 0; i < a.length; i++) {
+      out[i] = a[i] ^ b[i]
+    }
+    return out
+  }
+
+  /**
+   * Splits the 32-byte key into `this.CHUNK_COUNT` smaller chunks
+   * (mostly equal length; the last chunk picks up leftover bytes
+   * if 32 is not evenly divisible).
+   */
+  private splitKeyIntoChunks(keyBytes: Uint8Array): Uint8Array[] {
+    const chunkSize = Math.floor(keyBytes.length / this.CHUNK_COUNT)
+    const chunks: Uint8Array[] = []
+    let offset = 0
+
+    for (let i = 0; i < this.CHUNK_COUNT; i++) {
+      const size =
+        i === this.CHUNK_COUNT - 1 ? keyBytes.length - offset : chunkSize
+      chunks.push(keyBytes.slice(offset, offset + size))
+      offset += size
+    }
+    return chunks
+  }
+
+  /**
+   * Reassembles the chunks from the dynamic properties, XORs them
+   * with their corresponding pads, and returns a single 32-byte
+   * Uint8Array representing the raw key.
+   */
+  private reassembleKeyFromChunks(): Uint8Array | null {
+    try {
+      const chunkArrays: Uint8Array[] = []
+      for (let i = 0; i < this.chunkPropNames.length; i++) {
+        const chunkEnc = (this as any)[this.chunkPropNames[i]] as Uint8Array
+        const chunkPad = (this as any)[this.chunkPadPropNames[i]] as Uint8Array
+        if (!chunkEnc || !chunkPad || chunkEnc.length !== chunkPad.length) {
+          return null
+        }
+        const rawChunk = this.xorBytes(chunkEnc, chunkPad)
+        chunkArrays.push(rawChunk)
+      }
+      // Concat them back to a single 32-byte array:
+      const totalLength = chunkArrays.reduce((sum, c) => sum + c.length, 0)
+      if (totalLength !== 32) {
+        // We only handle 32-byte keys
+        return null
+      }
+      const rawKey = new Uint8Array(totalLength)
+      let offset = 0
+      for (const chunk of chunkArrays) {
+        rawKey.set(chunk, offset)
+        offset += chunk.length
+        // Attempt to zero the ephemeral chunk
+        chunk.fill(0)
+      }
+      return rawKey
+    } catch (_) {
+      // If any property is missing or type mismatch, we return null
+      return null
+    }
+  }
+
+  /**
+   * Generates a random property name to store key chunks or decoy data.
+   */
+  private generateRandomPropName(): string {
+    // E.g., 8 random hex characters for the property name
+    const randomHex = Utils.toHex(Random(4))
+    return `_${randomHex}_${Math.floor(Math.random() * 1e6)}`
+  }
+
+  /**
+   * Forces a PrivateKey to be represented as exactly 32 bytes, left-padding
+   * with zeros if its numeric value has fewer than 32 bytes.
+   */
+  private get32ByteRepresentation(privKey: PrivateKey): Uint8Array {
+    // The internal "toArray()" can be up to 32 bytes, but sometimes fewer
+    // if the numeric value has leading zeros.
+    const buf = privKey.toArray()
+    if (buf.length > 32) {
+      throw new Error(
+        'PrivilegedKeyManager: Expected a 32-byte key, but got more.'
+      )
+    }
+    // Left-pad with zeros if needed
+    const keyBytes = new Uint8Array(32)
+    keyBytes.set(buf, 32 - buf.length)
+    return keyBytes
+  }
+
+  /**
+   * Returns the privileged key needed to perform cryptographic operations.
+   * Uses in-memory chunk-based obfuscation if the key was already fetched.
+   * Otherwise, it calls out to `keyGetter`, splits the 32-byte representation
+   * of the key, XORs each chunk with a random pad, and stores them under
+   * dynamic property names. Also populates new decoy properties.
+   *
+   * @param reason - The reason for why the key is needed, passed to keyGetter.
+   * @returns The PrivateKey object needed for cryptographic operations.
+   */
+  private async getPrivilegedKey(reason: string): Promise<PrivateKey> {
+    // If we already have chunk properties, try reassemble
+    if (this.chunkPropNames.length > 0 && this.chunkPadPropNames.length > 0) {
+      const rawKeyBytes = this.reassembleKeyFromChunks()
+      if (rawKeyBytes && rawKeyBytes.length === 32) {
+        // Convert 32 raw bytes back to a PrivateKey
+        // (Leading zeros are preserved, but PrivateKey() will parse it as a big integer.)
+        const hexKey = Utils.toHex([...rawKeyBytes]) // 64 hex chars
+        rawKeyBytes.fill(0) // Zero ephemeral copy
+        this.scheduleKeyDestruction()
+        return new PrivateKey(hexKey, 'hex')
+      }
+    }
+
+    // Otherwise, fetch a fresh key from the secure environment
+    const fetchedKey = await this.keyGetter(reason)
+
+    // Force 32‑byte representation (left-pad if necessary)
+    const keyBytes = this.get32ByteRepresentation(fetchedKey)
+
+    // Clean up any old data first (in case we had something stale)
+    this.destroyKey()
+
+    // Split the key
+    const chunks = this.splitKeyIntoChunks(keyBytes)
+
+    // Store new chunk data under random property names
+    for (let i = 0; i < chunks.length; i++) {
+      const chunkProp = this.generateRandomPropName()
+      const padProp = this.generateRandomPropName()
+      this.chunkPropNames.push(chunkProp)
+      this.chunkPadPropNames.push(padProp)
+
+      // Generate random pad of the same length as the chunk
+      const pad = Uint8Array.from(Random(chunks[i].length))
+      // XOR the chunk to obfuscate
+      const obf = this.xorBytes(chunks[i], pad)
+
+      // Store them in dynamic properties
+      ;(this as any)[chunkProp] = obf
+      ;(this as any)[padProp] = pad
+    }
+
+    // Generate some decoy properties that will be destroyed with the key
+    for (let i = 0; i < 2; i++) {
+      const decoyProp = this.generateRandomPropName()
+      ;(this as any)[decoyProp] = Uint8Array.from(Random(32))
+      this.decoyPropNamesDestroy.push(decoyProp)
+    }
+
+    // Zero out ephemeral original
+    keyBytes.fill(0)
+
+    // Schedule destruction
+    this.scheduleKeyDestruction()
+
+    // Return the newly fetched key as a normal PrivateKey
+    return fetchedKey
+  }
+
+  async getPublicKey(
+    args: GetPublicKeyArgs
+  ): Promise<{ publicKey: PubKeyHex }> {
+    return new ProtoWallet(
+      await this.getPrivilegedKey(args.privilegedReason as string)
+    ).getPublicKey(args)
+  }
+
+  async revealCounterpartyKeyLinkage(
+    args: RevealCounterpartyKeyLinkageArgs
+  ): Promise<RevealCounterpartyKeyLinkageResult> {
+    return new ProtoWallet(
+      await this.getPrivilegedKey(args.privilegedReason as string)
+    ).revealCounterpartyKeyLinkage(args)
+  }
+
+  async revealSpecificKeyLinkage(
+    args: RevealSpecificKeyLinkageArgs
+  ): Promise<RevealSpecificKeyLinkageResult> {
+    return new ProtoWallet(
+      await this.getPrivilegedKey(args.privilegedReason as string)
+    ).revealSpecificKeyLinkage(args)
+  }
+
+  async encrypt(args: WalletEncryptArgs): Promise<WalletEncryptResult> {
+    return new ProtoWallet(
+      await this.getPrivilegedKey(args.privilegedReason as string)
+    ).encrypt(args)
+  }
+
+  async decrypt(args: WalletDecryptArgs): Promise<WalletDecryptResult> {
+    return new ProtoWallet(
+      await this.getPrivilegedKey(args.privilegedReason as string)
+    ).decrypt(args)
+  }
+
+  async createHmac(args: CreateHmacArgs): Promise<CreateHmacResult> {
+    return new ProtoWallet(
+      await this.getPrivilegedKey(args.privilegedReason as string)
+    ).createHmac(args)
+  }
+
+  async verifyHmac(args: VerifyHmacArgs): Promise<VerifyHmacResult> {
+    return new ProtoWallet(
+      await this.getPrivilegedKey(args.privilegedReason as string)
+    ).verifyHmac(args)
+  }
+
+  async createSignature(
+    args: CreateSignatureArgs
+  ): Promise<CreateSignatureResult> {
+    return new ProtoWallet(
+      await this.getPrivilegedKey(args.privilegedReason as string)
+    ).createSignature(args)
+  }
+
+  async verifySignature(
+    args: VerifySignatureArgs
+  ): Promise<VerifySignatureResult> {
+    return new ProtoWallet(
+      await this.getPrivilegedKey(args.privilegedReason as string)
+    ).verifySignature(args)
+  }
+}

package/src/sdk/README.md

@@ -0,0 +1,13 @@
+# Wallet SDK
+
+Primarily `interface` declarations of most abstract Wallet.interfaces related APIs.
+
+This includes:
+
+- Local copy of Wallet.interfaces, WalletCrypto, WalletSigner, ProtoWallet, CachedKeyDeriver to be merged back to `@bsv/ts-sdk`
+- Certificate and CertOps for standardized certificate handling.
+- WERR_errors.ts standard error classes.
+- WalletError standard error base class.
+- StorageSyncReadyer: a standard subset of WalletStorage for legacy import services.
+- validationHelpers non-asynchronous Wallet.interfaces args object validation methods and interfaces. For interface details standardization and enforcement.
+- `types` generic types for standardization.

package/src/sdk/StorageSyncReader.ts

@@ -0,0 +1,155 @@
+import { sdk, table } from '../index.client'
+
+/**
+ * This is the minimal interface required for a WalletStorageProvider to export data to another provider.
+ */
+export interface StorageSyncReader {
+  isAvailable(): boolean
+  makeAvailable(): Promise<table.Settings>
+
+  destroy(): Promise<void>
+
+  /////////////////
+  //
+  // READ OPERATIONS (state preserving methods)
+  //
+  /////////////////
+
+  getSettings(): table.Settings
+
+  findUserByIdentityKey(key: string): Promise<table.User | undefined>
+
+  findSyncStates(args: sdk.FindSyncStatesArgs): Promise<table.SyncState[]>
+
+  findCertificateFields(
+    args: sdk.FindCertificateFieldsArgs
+  ): Promise<table.CertificateField[]>
+  findCertificates(args: sdk.FindCertificatesArgs): Promise<table.Certificate[]>
+  findCommissions(args: sdk.FindCommissionsArgs): Promise<table.Commission[]>
+  findOutputBaskets(
+    args: sdk.FindOutputBasketsArgs
+  ): Promise<table.OutputBasket[]>
+  findOutputs(args: sdk.FindOutputsArgs): Promise<table.Output[]>
+  findOutputTags(args: sdk.FindOutputTagsArgs): Promise<table.OutputTag[]>
+  findTransactions(args: sdk.FindTransactionsArgs): Promise<table.Transaction[]>
+  findTxLabels(args: sdk.FindTxLabelsArgs): Promise<table.TxLabel[]>
+
+  getProvenTxsForUser(
+    args: sdk.FindForUserSincePagedArgs
+  ): Promise<table.ProvenTx[]>
+  getProvenTxReqsForUser(
+    args: sdk.FindForUserSincePagedArgs
+  ): Promise<table.ProvenTxReq[]>
+  getTxLabelMapsForUser(
+    args: sdk.FindForUserSincePagedArgs
+  ): Promise<table.TxLabelMap[]>
+  getOutputTagMapsForUser(
+    args: sdk.FindForUserSincePagedArgs
+  ): Promise<table.OutputTagMap[]>
+
+  getSyncChunk(args: RequestSyncChunkArgs): Promise<SyncChunk>
+}
+
+/**
+ * success: Last sync of this user from this storage was successful.
+ *
+ * error: Last sync protocol operation for this user to this storage threw and error.
+ *
+ * identified: Configured sync storage has been identified but not sync'ed.
+ *
+ * unknown: Sync protocol state is unknown.
+ */
+export type SyncStatus =
+  | 'success'
+  | 'error'
+  | 'identified'
+  | 'updated'
+  | 'unknown'
+
+export type SyncProtocolVersion = '0.1.0'
+
+export interface RequestSyncChunkArgs {
+  /**
+   * The storageIdentityKey of the storage supplying the update SyncChunk data.
+   */
+  fromStorageIdentityKey: string
+  /**
+   * The storageIdentityKey of the storage consuming the update SyncChunk data.
+   */
+  toStorageIdentityKey: string
+
+  /**
+   * The identity of whose data is being requested
+   */
+  identityKey: string
+  /**
+   * The max updated_at time received from the storage service receiving the request.
+   * Will be undefiend if this is the first request or if no data was previously sync'ed.
+   *
+   * `since` must include items if 'updated_at' is greater or equal. Thus, when not undefined, a sync request should always return at least one item already seen.
+   */
+  since?: Date
+  /**
+   * A rough limit on how large the response should be.
+   * The item that exceeds the limit is included and ends adding more items.
+   */
+  maxRoughSize: number
+  /**
+   * The maximum number of items (records) to be returned.
+   */
+  maxItems: number
+  /**
+   * For each entity in dependency order, the offset at which to start returning items
+   * from `since`.
+   *
+   * The entity order is:
+   * 0 ProvenTxs
+   * 1 ProvenTxReqs
+   * 2 OutputBaskets
+   * 3 TxLabels
+   * 4 OutputTags
+   * 5 Transactions
+   * 6 TxLabelMaps
+   * 7 Commissions
+   * 8 Outputs
+   * 9 OutputTagMaps
+   * 10 Certificates
+   * 11 CertificateFields
+   */
+  offsets: { name: string; offset: number }[]
+}
+
+/**
+ * Result received from remote `WalletStorage` in response to a `RequestSyncChunkArgs` request.
+ *
+ * Each property is undefined if there was no attempt to update it. Typically this is caused by size and count limits on this result.
+ *
+ * If all properties are empty arrays the sync process has received all available new and updated items.
+ */
+export interface SyncChunk {
+  fromStorageIdentityKey: string
+  toStorageIdentityKey: string
+  userIdentityKey: string
+
+  user?: table.User
+  provenTxs?: table.ProvenTx[]
+  provenTxReqs?: table.ProvenTxReq[]
+  outputBaskets?: table.OutputBasket[]
+  txLabels?: table.TxLabel[]
+  outputTags?: table.OutputTag[]
+  transactions?: table.Transaction[]
+  txLabelMaps?: table.TxLabelMap[]
+  commissions?: table.Commission[]
+  outputs?: table.Output[]
+  outputTagMaps?: table.OutputTagMap[]
+  certificates?: table.Certificate[]
+  certificateFields?: table.CertificateField[]
+}
+
+export interface ProcessSyncChunkResult {
+  done: boolean
+  maxUpdated_at: Date | undefined
+  updates: number
+  inserts: number
+  error?: sdk.WalletError
+}