@wishknish/knishio-client-ts 0.9.5 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "productName": "Knish.IO TypeScript SDK Client",
   "description": "TypeScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs with enhanced type safety.",
   "license": "GPL-3.0-or-later",
@@ -58,32 +58,30 @@
     "fips-203"
   ],
   "dependencies": {
-    "@noble/post-quantum": "^0.5.4",
-    "@thumbmarkjs/thumbmarkjs": "^0.19.1",
-    "@urql/core": "^5.2.0",
-    "graphql": "^16.11.0",
-    "graphql-ws": "^6.0.7",
-    "isomorphic-fetch": "^3.0.0",
-    "jssha": "^3.3.1",
+    "@noble/post-quantum": "^0.7.0",
+    "@urql/core": "^6.0.3",
+    "graphql": "^16.14.2",
+    "graphql-ws": "^6.2.1",
+    "jssha": "^3.3.2",
     "tslib": "^2.8.1",
-    "wonka": "^6.3.5",
+    "wonka": "^6.3.6",
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@types/isomorphic-fetch": "^0.0.39",
     "@types/jssha": "^3.0.0",
-    "@types/node": "^22",
-    "@typescript-eslint/eslint-plugin": "^8.63.0",
-    "@typescript-eslint/parser": "^8.63.0",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^9",
-    "prettier": "^3",
+    "@types/node": "^26",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10",
+    "prettier": "^3.9.6",
     "tsup": "^8.5.1",
-    "tsx": "^4.23.0",
+    "tsx": "^4.23.12",
     "typescript": "^5",
-    "vite": "^7",
-    "vite-plugin-dts": "^5.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
+  },
+  "resolutions": {
+    "wonka": "6.3.6"
   },
   "browserslist": [
     "> 1%",
@@ -103,7 +101,6 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
-    "dev": "vite",
     "prepublishOnly": "npm run build",
     "selftest": "npm run build && node self-test.cjs"
   },

package/src/KnishIOClient.ts

@@ -104,6 +104,7 @@ import MutationLinkIdentifier from '@/mutation/MutationLinkIdentifier'
 import MutationPeering from '@/mutation/MutationPeering'
 import MutationAppendRequest from '@/mutation/MutationAppendRequest'
 import MutationProposeMolecule from '@/mutation/MutationProposeMolecule'
+import MutationReplenishToken from '@/mutation/MutationReplenishToken'
 
 // Response imports
 import ResponseProposeMolecule from '@/response/ResponseProposeMolecule'
@@ -127,6 +128,8 @@ import {
   SignatureMismatchException,
   AtomIndexException
 } from '@/exception'
+import type { ISecretStorageProvider } from '@/types/storage'
+import MemorySecretStorageProvider from '@/storage/MemorySecretStorageProvider'
 
 // Type imports
 import type {
@@ -149,6 +152,7 @@ import type {
 export default class KnishIOClient {
   private $__secret: string = ''
   private $__bundle: string = ''
+  private $__secretStorage: ISecretStorageProvider | null = null
   private $__cellSlug: string | null = null
   private $__encrypt: boolean = false
   private $__uris: string[] = []
@@ -184,6 +188,7 @@ export default class KnishIOClient {
     serverSdkVersion?: number
     logging?: boolean
     defaultRequestPolicy?: RequestPolicy | null
+    secretStorage?: ISecretStorageProvider | null
   }) {
     // Phase 2 Enhancement: Use standardized configuration validation
     const standardValidationResult = ConfigValidator.validateClientConfig(config)
@@ -235,6 +240,10 @@ export default class KnishIOClient {
       logging,
       defaultRequestPolicy
     })
+
+    if (config.secretStorage) {
+      this.$__secretStorage = config.secretStorage
+    }
   }
 
   /**
@@ -364,6 +373,7 @@ export default class KnishIOClient {
   reset(): void {
     this.$__secret = ''
     this.$__bundle = ''
+    this.$__secretStorage = null
     this.$__encrypt = false
     this.$__cellSlug = null
     this.$__authToken = null
@@ -433,7 +443,7 @@ export default class KnishIOClient {
    * Returns whether a secret is stored for this session
    */
   hasSecret(): boolean {
-    return !!this.$__secret && this.$__secret.length > 0
+    return (!!this.$__secret && this.$__secret.length > 0) || (!!this.$__secretStorage && !!this.$__bundle && this.$__bundle.length > 0)
   }
 
   /**
@@ -446,6 +456,36 @@ export default class KnishIOClient {
     return this.$__secret
   }
 
+  /**
+   * Sets the secret storage provider and optionally sets the bundle hash
+   */
+  setSecretStorage(storage: ISecretStorageProvider, bundleHash?: string): void {
+    this.$__secretStorage = storage
+    if (bundleHash) {
+      this.$__bundle = bundleHash
+    }
+  }
+
+  /**
+   * Returns current secret storage provider
+   */
+  getSecretStorage(): ISecretStorageProvider | null {
+    return this.$__secretStorage
+  }
+
+  /**
+   * Asynchronously retrieves the secret from storage or returns in-memory secret
+   */
+  async retrieveSecret(options?: { passphrase?: string }): Promise<string | null> {
+    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
    */
@@ -494,6 +534,14 @@ export default class KnishIOClient {
   } = {}): Promise<Molecule> {
     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()
 
@@ -546,6 +594,7 @@ export default class KnishIOClient {
 
     return new Molecule({
       secret,
+      bundle,
       sourceWallet,
       remainderWallet: this.getRemainderWallet()!,
       cellSlug: this.getCellSlug(),
@@ -611,8 +660,9 @@ export default class KnishIOClient {
     // Guard with $__authInProcess to prevent recursive auth refresh
     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
       })
@@ -672,6 +722,13 @@ export default class KnishIOClient {
   setSecret(secret: string): void {
     this.$__secret = secret
     this.$__bundle = generateBundleHash(secret)
+    if (!this.$__secretStorage) {
+      const memStorage = new MemorySecretStorageProvider()
+      memStorage.storeSecret(this.$__bundle, secret)
+      this.$__secretStorage = memStorage
+    } else {
+      this.$__secretStorage.storeSecret(this.$__bundle, secret)
+    }
   }
 
   /**
@@ -923,6 +980,11 @@ export default class KnishIOClient {
       secret = generateSecret(seed)
     }
 
+    // Retrieve secret from storage provider if available
+    if (secret === null && this.$__secretStorage && this.$__bundle) {
+      secret = await this.$__secretStorage.retrieveSecret(this.$__bundle)
+    }
+
     // Set cell slug if provided
     if (cellSlug) {
       this.setCellSlug(cellSlug)
@@ -1836,27 +1898,55 @@ export default class KnishIOClient {
   }
 
   /**
-   * Replenish tokens
+   * Replenish a non-finite token supply.
+   * Matches JS SDK KnishIOClient.replenishToken (KnishIOClient.js:2195-2231).
    */
   async replenishToken({
     token,
     amount = null,
     units = null,
-    sourceWallet: _sourceWallet = null
+    sourceWallet = null
   }: {
     token: TokenSlug | string
     amount?: number | string | null
-    units?: string[] | null
+    units?: Array<[string, string, Record<string, any>?]> | null
     sourceWallet?: Wallet | null
   }): Promise<Response> {
     this.log('info', `KnishIOClient::replenishToken() - Replenishing ${amount || 'units'} of ${token}...`)
 
-    // Similar to requestTokens but with specific replenishment logic
-    return this.requestTokens({
-      token,
-      amount,
-      units
+    if (!sourceWallet) {
+      sourceWallet = (await this.queryBalance({ token }))?.payload() as Wallet | null
+    }
+    if (!sourceWallet) {
+      throw new TransferBalanceException('Source wallet is missing or invalid.')
+    }
+
+    // Remainder wallet (same token, so the V-isotope pair conserves)
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
     })
+    molecule.replenishToken({
+      amount: Number(amount ?? 0),
+      units: units ?? []
+    })
+    molecule.sign({ bundle: this.getBundle() })
+    molecule.check()
+
+    const mutation = await this.createMoleculeMutation({
+      mutationClass: MutationReplenishToken,
+      molecule
+    })
+
+    const response = await this.executeQuery(mutation)
+
+    if (!response) {
+      throw new CodeException('Token replenishment failed')
+    }
+
+    return response
   }
 
   /**

package/src/core/AtomMeta.ts

@@ -47,6 +47,7 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 */
 
 import Meta, { type NormalizedMeta } from './Meta'
+import PolicyMeta from './PolicyMeta'
 
 // Configuration constants matching JS SDK
 const USE_META_CONTEXT = false
@@ -172,12 +173,19 @@ export default class AtomMeta {
    * @return This instance for chaining
    */
   addPolicy(policy: Record<string, any>): AtomMeta {
-    // For now, just stringify the policy
-    // TODO: Implement PolicyMeta class if needed
+    // Normalise through PolicyMeta before serialising. PolicyMeta.fillDefault adds a default
+    // entry for every meta key not already covered by the caller's policy, so the stored string
+    // carries materially more than the input — and this string is hashed into the atom, so a
+    // raw JSON.stringify(policy) diverges from every other SDK.
+    // Matches JS SDK AtomMeta.addPolicy (AtomMeta.js:170-175), including passing
+    // Object.keys(this.meta): `meta` is a NormalizedMeta[] in both SDKs, so these are array
+    // indices rather than meta key names. Faithful to the JS behaviour — do not "correct" it.
+    const policyMeta = new PolicyMeta(policy, Object.keys(this.meta))
+
     this.merge({
-      policy: JSON.stringify(policy)
+      policy: policyMeta.toJson()
     })
-    
+
     return this
   }
 

package/src/core/Molecule.ts

@@ -755,6 +755,67 @@ export default class Molecule {
     return this
   }
 
+  /**
+   * Replenishes non-finite token supplies.
+   * Matches JS SDK Molecule.replenishToken (Molecule.js:521-566) exactly.
+   *
+   * Two orderings here are load-bearing for the molecular hash and must not be reordered:
+   * the remainder balance is computed BEFORE the source balance is overwritten, and the
+   * source V-atom is added BEFORE the remainder V-atom.
+   */
+  replenishToken({
+    amount,
+    units = []
+  }: {
+    amount: number
+    units?: Array<[string, string, Record<string, any>?]>
+  }): Molecule {
+    if (amount < 0) {
+      throw new NegativeAmountException('Molecule::replenishToken() - Amount to replenish must be positive!')
+    }
+
+    if (!this.sourceWallet || !this.remainderWallet) {
+      throw new Error('Source and remainder wallets required for token replenishment')
+    }
+
+    if (units.length) {
+      // Prepare token units to formatted style
+      const formatted = Wallet.getTokenUnits(units)
+
+      // Merge token units with source wallet & new items
+      this.remainderWallet.tokenUnits = this.sourceWallet.tokenUnits
+      for (const unit of formatted) {
+        this.remainderWallet.tokenUnits.push(unit)
+      }
+      this.remainderWallet.balance = String(this.remainderWallet.tokenUnits.length)
+
+      // Override first atom's token units to replenish values
+      this.sourceWallet.tokenUnits = formatted
+      this.sourceWallet.balance = String(this.sourceWallet.tokenUnits.length)
+    } else {
+      // Update wallet's balances
+      this.remainderWallet.balance = String(Number(this.sourceWallet.balance) + amount)
+      this.sourceWallet.balance = String(amount)
+    }
+
+    // Initializing a new Atom to remove tokens from source
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.sourceWallet,
+      value: Number(this.sourceWallet.balance)
+    }))
+
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.remainderWallet,
+      value: Number(this.remainderWallet.balance),
+      metaType: 'walletBundle',
+      metaId: this.remainderWallet.bundle!
+    }))
+
+    return this
+  }
+
   /**
    * Initialize authorization request
    * Creates U-isotope (authorization) atom for requesting auth token

package/src/core/Wallet.ts

@@ -51,6 +51,7 @@ import { randomString, chunkSubstr, isHex } from '@/libraries/strings'
 import { generateBundleHash, generateSecret, shake256, generateBatchId } from '@/libraries/crypto'
 import WalletCredentialException from '@/exception/WalletCredentialException'
 import { isBundleHash } from '@/types'
+import TokenUnit from '@/core/TokenUnit'
 // Post-quantum cryptography for ML-KEM768 key encapsulation
 import { ml_kem768 } from '@noble/post-quantum/ml-kem.js'
 
@@ -271,12 +272,13 @@ export default class Wallet {
   }
 
   /**
-   * Get formatted token units from raw data
-   * Stub implementation for now
+   * Map raw token-unit tuples to TokenUnit instances.
+   * Matches JS SDK Wallet.getTokenUnits (Wallet.js:190-196). The serialised shape reaches hashed
+   * atom meta via AtomMeta.setAtomWallet -> JSON.stringify(getTokenUnitsData()), so returning raw
+   * tuples here would diverge from every other SDK.
    */
-  static getTokenUnits(unitsData: any[]): any[] {
-    // TODO: Implement TokenUnit class if needed
-    return unitsData
+  static getTokenUnits(unitsData: Array<[string, string, Record<string, any>?]>): TokenUnit[] {
+    return unitsData.map(unitData => TokenUnit.createFromDB(unitData))
   }
 
   /**

package/src/exception/SecretStorageException.ts

@@ -0,0 +1,97 @@
+/*
+                               (
+                              (/(
+                              (//(
+                              (///(
+                             (/////(
+                             (//////(                          )
+                            (////////(                        (/)
+                            (////////(                       (///)
+                           (//////////(                      (////)
+                           (//////////(                     (//////)
+                          (////////////(                    (///////)
+                         (/////////////(                   (/////////)
+                        (//////////////(                  (///////////)
+                        (///////////////(                (/////////////)
+                       (////////////////(               (//////////////)
+                      (((((((((((((((((((              (((((((((((((((
+                     (((((((((((((((((((              ((((((((((((((
+                     (((((((((((((((((((            ((((((((((((((
+                    ((((((((((((((((((((           (((((((((((((
+                    ((((((((((((((((((((          ((((((((((((
+                    (((((((((((((((((((         ((((((((((((
+                    (((((((((((((((((((        ((((((((((
+                    ((((((((((((((((((/      (((((((((
+                    ((((((((((((((((((     ((((((((
+                    (((((((((((((((((    (((((((
+                   ((((((((((((((((((  (((((
+                   #################  ##
+                   ################  #
+                  ################# ##
+                 %################  ###
+                 ###############(   ####
+                ###############      ####
+               ###############       ######
+              %#############(        (#######
+             %#############           #########
+            ############(              ##########
+           ###########                  #############
+          #########                      ##############
+        %######
+
+        Powered by Knish.IO: Connecting a Decentralized World
+
+Please visit https://github.com/WishKnish/KnishIO-Client-TS for information.
+
+License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
+*/
+
+import BaseException, { type BaseExceptionOptions } from './BaseException'
+
+/**
+ * Exception thrown when a secret storage or hardware envelope encryption operation fails
+ */
+export default class SecretStorageException extends BaseException {
+  constructor(message = 'Secret storage operation failed', options: BaseExceptionOptions = {}) {
+    super('WALLET_CREDENTIAL_ERROR', message, {
+      code: 'SECRET_STORAGE_ERROR',
+      ...options
+    })
+  }
+
+  /**
+   * Secret not found for the requested bundle hash
+   */
+  static notFound(bundleHash: string): SecretStorageException {
+    return new SecretStorageException(`Secret not found for bundle: ${bundleHash}`, {
+      code: 'SECRET_NOT_FOUND',
+      details: { bundleHash }
+    })
+  }
+
+  /**
+   * Decryption failed (wrong passphrase or corrupted payload)
+   */
+  static decryptionFailed(reason?: string): SecretStorageException {
+    return new SecretStorageException(
+      `Failed to decrypt master secret: ${reason || 'Invalid passphrase or corrupted ciphertext'}`,
+      {
+        code: 'DECRYPTION_FAILED',
+        details: { reason }
+      }
+    )
+  }
+
+  /**
+   * Provider is unavailable in current platform
+   */
+  static unavailable(provider: string, reason?: string): SecretStorageException {
+    return new SecretStorageException(
+      `Secret storage provider '${provider}' is unavailable: ${reason || 'Hardware or API not accessible'}`,
+      {
+        code: 'STORAGE_UNAVAILABLE',
+        details: { provider, reason }
+      }
+    )
+  }
+}

package/src/exception/index.ts

@@ -62,6 +62,7 @@ export { default as MolecularHashMismatchException } from './MolecularHashMismat
 export { default as SignatureMismatchException } from './SignatureMismatchException'
 export { default as TransferBalanceException } from './TransferBalanceException'
 export { default as WalletCredentialException } from './WalletCredentialException'
+export { default as SecretStorageException } from './SecretStorageException'
 export { default as InvalidResponseException } from './InvalidResponseException'
 
 // Additional exceptions (now implemented)

package/src/index.ts

@@ -261,12 +261,39 @@ export {
   SignatureMismatchException,
   TransferBalanceException,
   WalletCredentialException,
+  SecretStorageException,
   InvalidResponseException,
   ExceptionFactory,
   EXCEPTION_TYPES,
   EXCEPTION_CODES
 } from './exception'
 
+// =============================================================================
+// SECRET STORAGE & HARDWARE ENVELOPE ENCRYPTION
+// =============================================================================
+
+export {
+  MemorySecretStorageProvider,
+  WebCryptoSecretStorageProvider,
+  MemoryStorageBackend,
+  createDefaultSecretStorage,
+  type IStorageBackend,
+  type CreateSecretStorageOptions
+} from './storage'
+
+export {
+  zeroizeBytes,
+  withSecureBytes,
+  withSecureString,
+  constantTimeCompare
+} from './libraries/secureMemory'
+
+export type {
+  SecretStorageMetadata,
+  EncryptedSecretPayload,
+  ISecretStorageProvider
+} from './types/storage'
+
 // =============================================================================
 // TYPE DEFINITIONS
 // =============================================================================
@@ -362,7 +389,7 @@ export {
 // MUST equal package.json's "version". The CI `version consistency` job enforces this via
 // .github/scripts/check-version.sh, which parses this exact line — keep the literal form
 // `export const SDK_VERSION = '<semver>'` intact so the gate can read it.
-export const SDK_VERSION = '0.9.5'
+export const SDK_VERSION = '0.9.7'
 export const SDK_NAME = 'KnishIO-Client-TS'
 export const COMPATIBLE_SERVER_VERSIONS = [4, 5]
 

package/src/libraries/GraphQLClient.ts

@@ -141,16 +141,30 @@ export default class GraphQLClient implements IGraphQLClient {
     return createClient({
       url: serverUri,
       exchanges,
-      // PQ-transport Phase E: when encryption is on, route fetch through the CipherHash wrapper
-      // (encrypt the request body to the validator's ML-KEM pubkey, decrypt the response).
-      // Omitted → urql uses the global fetch (plaintext).
-      ...(this.cipherLink ? { fetch: ((input: any, init: any) => this.cipherFetch(input, init)) as typeof fetch } : {}),
+      // urql 5 had no default and always POSTed; urql 6 defaults to 'within-url-limit', which
+      // URL-encodes short queries and sends NO body. That would silently disable the CipherHash
+      // envelope below — cipherFetch's `typeof init.body === 'string'` guard fails on a GET, so
+      // the query would leave as plaintext URL parameters with no error. Pin POST explicitly.
+      preferGetMethod: false,
+      // Always route through our own fetch. Two reasons: (1) PQ-transport Phase E — when
+      // encryption is on, cipherFetch wraps the request body in the CipherHash envelope and
+      // decrypts the response; (2) the 60s timeout. urql's makeFetchSource unconditionally
+      // overwrites init.signal with its own AbortController, so a signal returned from
+      // fetchOptions() is discarded and never fired. Combining it here is the only place it
+      // survives.
+      fetch: ((input: RequestInfo | URL, init?: RequestInit) => {
+        const timeoutSignal = AbortSignal.timeout(60000)
+        // Keep urql's own signal so teardown still aborts; AbortSignal.any needs Node >= 18.17.
+        const signal = init?.signal && typeof AbortSignal.any === 'function'
+          ? AbortSignal.any([init.signal, timeoutSignal])
+          : (init?.signal ?? timeoutSignal)
+        const timedInit: RequestInit = { ...init, signal }
+        return this.cipherLink ? this.cipherFetch(input, timedInit) : fetch(input, timedInit)
+      }) as typeof fetch,
       fetchOptions: () => ({
         headers: {
           'X-Auth-Token': this.$__authToken
-        },
-        // Add 60 second timeout
-        signal: AbortSignal.timeout(60000)
+        }
       })
     })
   }

package/src/libraries/UrqlClientWrapper.ts

@@ -155,12 +155,17 @@ class UrqlClientWrapper {
     return createClient({
       url: serverUri,
       exchanges,
+      // urql 6 defaults preferGetMethod to 'within-url-limit', sending short queries as GET with
+      // no body. Keep the urql-5 behaviour (always POST) so this client matches GraphQLClient and
+      // cannot silently change the wire format if it is ever put back into use.
+      preferGetMethod: false,
+      // No `signal` here: urql's makeFetchSource overwrites init.signal with its own
+      // AbortController, so a timeout passed through fetchOptions() is silently discarded and
+      // never fires. GraphQLClient applies its 60s timeout inside a wrapping `fetch` instead.
       fetchOptions: () => ({
         headers: {
           'X-Auth-Token': this.$__authToken
-        },
-        // Add 60 second timeout for debugging
-        signal: AbortSignal.timeout(60000)
+        }
       })
     })
   }

package/src/libraries/crypto.ts

@@ -659,13 +659,11 @@ export function verifyOTSSignature(
     const enumerated = enumerateMolecularHash(base17Hash)
     const normalized = normalizeMolecularHash(enumerated)
     
-    // Step 2: Process OTS fragments (handle compression if needed)
-    let ots = otsFragments
+    // Step 2: Fragments must be the uncompressed 2048-character form. Base64-compressed
+    // signatures are not supported and are rejected here rather than expanded.
+    const ots = otsFragments
     if (ots.length !== 2048) {
-      // If not 2048 chars, it might be base64 compressed - for now, assume uncompressed
-      if (ots.length !== 2048) {
-        return false // Invalid signature length
-      }
+      return false
     }
     
     // Step 3: Subdivide OTS into 16 segments of 128 characters each