@wishknish/knishio-client-js 0.9.2 → 0.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-js",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "type": "module",
   "productName": "Knish.IO Javascript SDK Client",
   "description": "JavaScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs.",
@@ -96,5 +96,5 @@
     "/src",
     "/dist"
   ],
-  "packageManager": "yarn@4.9.2"
+  "packageManager": "yarn@4.15.0"
 }

package/src/KnishIOClient.js

@@ -46,6 +46,7 @@ Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
 License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
  */
 import Dot from './libraries/Dot.js'
+import MemorySecretStorageProvider from './storage/MemorySecretStorageProvider.js'
 import Decimal from './libraries/Decimal.js'
 import {
   generateBatchId,
@@ -127,7 +128,8 @@ export default class KnishIOClient {
     socket = null,
     serverSdkVersion = 3,
     logging = false,
-    defaultRequestPolicy = null
+    defaultRequestPolicy = null,
+    secretStorage = null
   }) {
     this.initialize({
       uri,
@@ -136,7 +138,8 @@ export default class KnishIOClient {
       client,
       serverSdkVersion,
       logging,
-      defaultRequestPolicy
+      defaultRequestPolicy,
+      secretStorage
     })
   }
 
@@ -157,10 +160,12 @@ export default class KnishIOClient {
     client = null,
     serverSdkVersion = 3,
     logging = false,
-    defaultRequestPolicy = null
+    defaultRequestPolicy = null,
+    secretStorage = null
   }) {
     this.reset()
 
+    this.$__secretStorage = secretStorage
     this.$__logging = logging
     // Client-level urql request policy applied to reads that omit a per-call
     // policy. A long-lived server/sync client set to 'network-only' never serves
@@ -278,6 +283,7 @@ export default class KnishIOClient {
   reset () {
     this.$__secret = ''
     this.$__bundle = ''
+    this.$__secretStorage = null
     this.remainderWallet = null
     this.$__capabilityCache = {}
     this.$__defaultRequestPolicy = null
@@ -376,7 +382,7 @@ export default class KnishIOClient {
    * @return {boolean}
    */
   hasSecret () {
-    return !!this.$__secret
+    return (!!this.$__secret && this.$__secret.length > 0) || (!!this.$__secretStorage && !!this.$__bundle && this.$__bundle.length > 0)
   }
 
   /**
@@ -387,6 +393,13 @@ export default class KnishIOClient {
   setSecret (secret) {
     this.$__secret = secret
     this.$__bundle = this.hashSecret(secret, 'setSecret')
+    if (!this.$__secretStorage) {
+      const memStorage = new MemorySecretStorageProvider()
+      memStorage.storeSecret(this.$__bundle, secret)
+      this.$__secretStorage = memStorage
+    } else {
+      this.$__secretStorage.storeSecret(this.$__bundle, secret)
+    }
   }
 
   /**
@@ -412,6 +425,44 @@ export default class KnishIOClient {
     return this.$__secret
   }
 
+  /**
+   * Sets the secret storage provider and optionally sets the bundle hash
+   *
+   * @param {object} storage
+   * @param {string|null} [bundleHash]
+   */
+  setSecretStorage (storage, bundleHash = null) {
+    this.$__secretStorage = storage
+    if (bundleHash) {
+      this.$__bundle = bundleHash
+    }
+  }
+
+  /**
+   * Returns current secret storage provider
+   *
+   * @returns {object|null}
+   */
+  getSecretStorage () {
+    return this.$__secretStorage
+  }
+
+  /**
+   * Asynchronously retrieves the secret from storage or returns in-memory secret
+   *
+   * @param {object} [options]
+   * @returns {Promise<string|null>}
+   */
+  async retrieveSecret (options = {}) {
+    if (this.$__secret && this.$__secret.length > 0) {
+      return this.$__secret
+    }
+    if (this.$__secretStorage && this.$__bundle && this.$__bundle.length > 0) {
+      return await this.$__secretStorage.retrieveSecret(this.$__bundle, options)
+    }
+    return null
+  }
+
   /**
    * Returns whether a bundle hash is being stored for this session
    *
@@ -496,10 +547,16 @@ export default class KnishIOClient {
     remainderWallet = null
   }) {
     this.log('info', 'KnishIOClient::createMolecule() - Creating a new molecule...')
+    if (!secret) {
+      if (this.$__secret && this.$__secret.length > 0) {
+        secret = this.getSecret()
+      } else if (this.$__secretStorage && this.$__bundle && this.$__bundle.length > 0) {
+        secret = await this.$__secretStorage.retrieveSecret(this.$__bundle)
+      }
+    }
 
     secret = secret || this.getSecret()
     bundle = bundle || this.getBundle()
-
     // For non-USER source wallets (V/B isotopes), capture the current USER
     // ContinuID position BEFORE overwriting the client's remainder wallet.
     // This position is needed by addContinuIdAtom() for previousPosition metadata.
@@ -546,6 +603,7 @@ export default class KnishIOClient {
 
     return new Molecule({
       secret,
+      bundle,
       sourceWallet,
       remainderWallet: this.getRemainderWallet(),
       cellSlug: this.getCellSlug(),
@@ -611,8 +669,9 @@ export default class KnishIOClient {
     // Guard with $__authInProcess to prevent concurrent auth requests
     if (this.$__authToken && this.$__authToken.isExpired() && !this.$__authInProcess) {
       this.log('info', 'KnishIOClient::executeQuery() - Access token is expired. Getting new one...')
+      const authSecret = this.$__secret || (await this.retrieveSecret()) || ''
       await this.requestAuthToken({
-        secret: this.$__secret,
+        secret: authSecret,
         cellSlug: this.$__cellSlug,
         encrypt: this.$__encrypt
       })
@@ -2464,6 +2523,11 @@ export default class KnishIOClient {
       this.setCellSlug(cellSlug)
     }
 
+    // Retrieve secret from storage provider if available
+    if (secret === null && this.$__secretStorage && this.$__bundle) {
+      secret = await this.$__secretStorage.retrieveSecret(this.$__bundle)
+    }
+
     // Auth in process...
     this.$__authInProcess = true
 

package/src/Molecule.js

@@ -1080,7 +1080,7 @@ export default class Molecule {
     bundle = null,
     anonymous = false,
     compressed = true
-  }) {
+  } = {}) {
     // Do we have atoms?
     if (this.atoms.length === 0 || this.atoms.filter(atom => !(atom instanceof Atom)).length !== 0) {
       throw new AtomsMissingException()

package/src/Wallet.js

@@ -300,10 +300,23 @@ export default class Wallet {
   }
 
   serializeKey (key) {
-    return btoa(String.fromCharCode.apply(null, key))
+    if (typeof Buffer !== 'undefined') {
+      return Buffer.from(key).toString('base64')
+    }
+    // String.fromCharCode.apply(null, key) overflows the call stack once the
+    // payload exceeds the engine's argument limit (~64K), so convert in chunks.
+    let binary = ''
+    const CHUNK_SIZE = 0x8000
+    for (let i = 0; i < key.length; i += CHUNK_SIZE) {
+      binary += String.fromCharCode(...key.subarray(i, i + CHUNK_SIZE))
+    }
+    return btoa(binary)
   }
 
   deserializeKey (serializedKey) {
+    if (typeof Buffer !== 'undefined') {
+      return new Uint8Array(Buffer.from(serializedKey, 'base64'))
+    }
     const binaryString = atob(serializedKey)
     return new Uint8Array(binaryString.length).map((_, i) => binaryString.charCodeAt(i))
   }

package/src/exception/SecretStorageException.js

@@ -0,0 +1,95 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
+*/
+
+import BaseException from './BaseException.js'
+
+/**
+ * Exception thrown when secret storage or hardware envelope encryption fails
+ */
+export default class SecretStorageException extends BaseException {
+  /**
+   * @param {string} message
+   * @param {string|null} fileName
+   * @param {number|null} lineNumber
+   */
+  constructor (message = 'Secret storage operation failed', fileName = null, lineNumber = null) {
+    super(message, fileName, lineNumber)
+    this.name = 'SecretStorageException'
+  }
+
+  /**
+   * Factory method: secret not found for bundle
+   *
+   * @param {string} bundleHash
+   * @returns {SecretStorageException}
+   */
+  static notFound (bundleHash) {
+    return new SecretStorageException(`Secret not found for bundle: ${bundleHash}`)
+  }
+
+  /**
+   * Factory method: decryption failed
+   *
+   * @param {string} [reason]
+   * @returns {SecretStorageException}
+   */
+  static decryptionFailed (reason = 'Invalid passphrase or corrupted ciphertext') {
+    return new SecretStorageException(`Failed to decrypt master secret: ${reason}`)
+  }
+
+  /**
+   * Factory method: provider unavailable
+   *
+   * @param {string} provider
+   * @param {string} [reason]
+   * @returns {SecretStorageException}
+   */
+  static unavailable (provider, reason = 'Hardware or API not accessible') {
+    return new SecretStorageException(`Secret storage provider '${provider}' is unavailable: ${reason}`)
+  }
+}

package/src/exception/index.js

@@ -70,6 +70,7 @@ import TransferUnbalancedException from './TransferUnbalancedException.js'
 import UnauthenticatedException from './UnauthenticatedException.js'
 import WalletShadowException from './WalletShadowException.js'
 import WrongTokenTypeException from './WrongTokenTypeException.js'
+import SecretStorageException from './SecretStorageException.js'
 
 export {
   AtomIndexException,
@@ -96,5 +97,6 @@ export {
   TransferUnbalancedException,
   UnauthenticatedException,
   WalletShadowException,
+  SecretStorageException,
   WrongTokenTypeException
 }

package/src/index.js

@@ -207,6 +207,7 @@ export {
   TransferUnbalancedException,
   UnauthenticatedException,
   WalletShadowException,
+  SecretStorageException,
   WrongTokenTypeException
 } from './exception/index.js'
 
@@ -325,3 +326,17 @@ export {
   diff,
   intersect
 }
+
+export {
+  MemorySecretStorageProvider,
+  WebCryptoSecretStorageProvider,
+  MemoryStorageBackend,
+  createDefaultSecretStorage
+} from './storage/index.js'
+
+export {
+  zeroizeBytes,
+  withSecureBytes,
+  withSecureString,
+  constantTimeCompare
+} from './libraries/secureMemory.js'

package/src/libraries/array.js

@@ -6,11 +6,13 @@
  * @return {array}
  */
 export function chunkArray (arr, size) {
-  if (!arr.length) {
-    return []
+  // Iterative: the previous recursive form (`concat` + `slice(size)` per level) blew
+  // the call stack and allocated O(n^2) once arr grew past a few thousand elements.
+  const chunks = []
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size))
   }
-
-  return [arr.slice(0, size)].concat(chunkArray(arr.slice(size), size))
+  return chunks
 }
 
 export function deepCloning (

package/src/libraries/secureMemory.js

@@ -0,0 +1,125 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-JS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-JS/blob/master/LICENSE
+*/
+
+/**
+ * Memory hygiene and zeroization utilities for sensitive cryptographic material
+ */
+
+const textEncoder = new TextEncoder()
+
+/**
+ * Overwrite byte array contents with zeros
+ *
+ * @param {Uint8Array|number[]} buffer
+ */
+export function zeroizeBytes (buffer) {
+  if (buffer instanceof Uint8Array) {
+    buffer.fill(0)
+  } else if (Array.isArray(buffer)) {
+    for (let i = 0; i < buffer.length; i++) {
+      buffer[i] = 0
+    }
+  }
+}
+
+/**
+ * Execute a callback with a byte buffer and guarantee zeroization upon completion
+ *
+ * @template T
+ * @param {Uint8Array} bytes
+ * @param {(bytes: Uint8Array) => Promise<T>|T} fn
+ * @returns {Promise<T>}
+ */
+export async function withSecureBytes (bytes, fn) {
+  try {
+    return await fn(bytes)
+  } finally {
+    zeroizeBytes(bytes)
+  }
+}
+
+/**
+ * Execute a callback with a secret string, ensuring temporary byte buffers are cleared
+ *
+ * @template T
+ * @param {string} secret
+ * @param {(cleanSecret: string) => Promise<T>|T} fn
+ * @returns {Promise<T>}
+ */
+export async function withSecureString (secret, fn) {
+  const bytes = textEncoder.encode(secret)
+  try {
+    return await fn(secret)
+  } finally {
+    zeroizeBytes(bytes)
+  }
+}
+
+/**
+ * Constant-time comparison of two byte arrays or strings to prevent timing attacks
+ *
+ * @param {Uint8Array|string} a
+ * @param {Uint8Array|string} b
+ * @returns {boolean}
+ */
+export function constantTimeCompare (a, b) {
+  const bytesA = typeof a === 'string' ? textEncoder.encode(a) : a
+  const bytesB = typeof b === 'string' ? textEncoder.encode(b) : b
+
+  let result = bytesA.length === bytesB.length ? 0 : 1
+  const len = Math.min(bytesA.length, bytesB.length)
+
+  for (let i = 0; i < len; i++) {
+    result |= (bytesA[i] ?? 0) ^ (bytesB[i] ?? 0)
+  }
+
+  if (typeof a === 'string') zeroizeBytes(bytesA)
+  if (typeof b === 'string') zeroizeBytes(bytesB)
+
+  return result === 0
+}

package/src/libraries/strings.js

@@ -45,13 +45,18 @@ export function chunkSubstr (str, size) {
  * @return {string}
  */
 export function randomString (length = 256, alphabet = 'abcdef0123456789') {
-  let array = new Uint8Array(length)
+  const array = new Uint8Array(length)
 
-  array = crypto.getRandomValues(array)
+  crypto.getRandomValues(array)
 
-  array = array.map(x => alphabet.charCodeAt(x % alphabet.length))
-
-  return String.fromCharCode.apply(null, array)
+  // Build in a loop: String.fromCharCode.apply(null, array) spread every byte as a
+  // function argument and overflowed the call stack for a large caller-supplied length.
+  // `alphabet.charAt(x % len)` is the same mapping as the old fromCharCode(charCodeAt).
+  let result = ''
+  for (let i = 0; i < length; i++) {
+    result += alphabet.charAt(array[i] % alphabet.length)
+  }
+  return result
 }
 
 /**
@@ -120,7 +125,19 @@ export function hexStringToBuffer (hexString) {
  */
 export function hexToBase64 (string) {
   const bytes = hexStringToBuffer(string)
-  return btoa(String.fromCharCode.apply(null, bytes))
+  // Buffer fast path (Node). Byte-identical to the btoa encoding below.
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64')
+  }
+  // Browser fallback: String.fromCharCode.apply(null, bytes) spreads every byte as a
+  // function argument and overflows the call stack past the engine's argument limit
+  // (~64K), so convert in chunks.
+  let binary = ''
+  const CHUNK_SIZE = 0x8000
+  for (let i = 0; i < bytes.length; i += CHUNK_SIZE) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK_SIZE))
+  }
+  return btoa(binary)
 }
 
 /**
@@ -130,7 +147,16 @@ export function hexToBase64 (string) {
  * @return {string}
  */
 export function base64ToHex (string) {
-  const bytes = new Uint8Array(atob(string).split('').map(char => char.charCodeAt(0)))
+  // Buffer fast path (Node); index loop otherwise. The old `atob(string).split('')`
+  // allocated one single-char string per byte — prohibitive for multi-MB payloads.
+  if (typeof Buffer !== 'undefined') {
+    return bufferToHexString(new Uint8Array(Buffer.from(string, 'base64')))
+  }
+  const binary = atob(string)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
   return bufferToHexString(bytes)
 }