@wishknish/knishio-client-js 0.9.3 → 0.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-js",
-  "version": "0.9.3",
+  "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/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/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/storage/MemorySecretStorageProvider.js

@@ -0,0 +1,170 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        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 SecretStorageException from '../exception/SecretStorageException.js'
+import { withSecureString } from '../libraries/secureMemory.js'
+
+/**
+ * In-memory secret storage provider
+ * Used for testing, headless runners, and backward-compatible fallback
+ */
+export default class MemorySecretStorageProvider {
+  constructor () {
+    this.providerType = 'memory'
+    this.secrets = new Map()
+  }
+
+  /**
+   * Memory storage is not hardware backed
+   *
+   * @returns {boolean}
+   */
+  isHardwareBacked () {
+    return false
+  }
+
+  /**
+   * Memory storage is always available
+   *
+   * @returns {Promise<boolean>}
+   */
+  async isAvailable () {
+    return true
+  }
+
+  /**
+   * Store a secret in memory
+   *
+   * @param {string} bundleHash
+   * @param {string} secret
+   * @param {{ label?: string }} [options]
+   * @returns {Promise<void>}
+   */
+  async storeSecret (bundleHash, secret, options = {}) {
+    if (!bundleHash) {
+      throw new SecretStorageException('Bundle hash cannot be empty')
+    }
+    if (!secret) {
+      throw new SecretStorageException('Secret cannot be empty')
+    }
+
+    const metadata = {
+      bundleHash,
+      label: options.label,
+      createdAt: Date.now(),
+      hardwareBacked: false,
+      providerType: this.providerType
+    }
+
+    this.secrets.set(bundleHash, { secret, metadata })
+  }
+
+  /**
+   * Retrieve a secret from memory
+   *
+   * @param {string} bundleHash
+   * @returns {Promise<string|null>}
+   */
+  async retrieveSecret (bundleHash) {
+    const entry = this.secrets.get(bundleHash)
+    return entry ? entry.secret : null
+  }
+
+  /**
+   * Delete a stored secret
+   *
+   * @param {string} bundleHash
+   * @returns {Promise<boolean>}
+   */
+  async deleteSecret (bundleHash) {
+    return this.secrets.delete(bundleHash)
+  }
+
+  /**
+   * Check if a secret exists
+   *
+   * @param {string} bundleHash
+   * @returns {Promise<boolean>}
+   */
+  async hasSecret (bundleHash) {
+    return this.secrets.has(bundleHash)
+  }
+
+  /**
+   * List all stored secret metadata
+   *
+   * @returns {Promise<Array<{ bundleHash: string, label?: string, createdAt: number, hardwareBacked: boolean, providerType: string }>>}
+   */
+  async listSecrets () {
+    return Array.from(this.secrets.values()).map(entry => ({ ...entry.metadata }))
+  }
+
+  /**
+   * Execute callback with unwrapped secret and ensure cleanup
+   *
+   * @template T
+   * @param {string} bundleHash
+   * @param {(secret: string) => Promise<T>|T} fn
+   * @returns {Promise<T>}
+   */
+  async withSecret (bundleHash, fn) {
+    const entry = this.secrets.get(bundleHash)
+    if (!entry) {
+      throw SecretStorageException.notFound(bundleHash)
+    }
+
+    return withSecureString(entry.secret, fn)
+  }
+
+  /**
+   * Clear all secrets from memory
+   */
+  clear () {
+    this.secrets.clear()
+  }
+}