@wishknish/knishio-client-js 0.9.3 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-js",
-  "version": "0.9.3",
+  "version": "1.0.0",
   "type": "module",
   "productName": "Knish.IO Javascript SDK Client",
   "description": "JavaScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs.",
@@ -48,16 +48,16 @@
     "quantum-safe",
     "sdk",
     "javascript",
-    "ml-kem768",
+    "ml-kem1024",
     "cryptography",
     "crystals-kyber",
     "fips-202",
     "fips-203"
   ],
   "dependencies": {
-    "@noble/post-quantum": "^0.5.4",
-    "@thumbmarkjs/thumbmarkjs": "^0.19.1",
-    "@urql/core": "^5.2.0",
+    "@noble/post-quantum": "^0.7.1",
+    "@thumbmarkjs/thumbmarkjs": "^1.11.0",
+    "@urql/core": "^6.0.3",
     "graphql": "^16.12.0",
     "graphql-ws": "^6.0.7",
     "isomorphic-fetch": "^3.0.0",
@@ -66,17 +66,13 @@
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
-    "@rollup/plugin-babel": "^6.1.0",
-    "@rollup/plugin-commonjs": "^28.0.9",
-    "@rollup/plugin-node-resolve": "^16.0.3",
     "@swc/core": "^1.15.43",
     "@swc/jest": "^0.2.39",
     "buffer": "^6.0.3",
     "eslint": "^9.39.0",
     "jest": "^30.4.2",
     "neostandard": "^0.13.0",
-    "rollup": "^4.57.1",
-    "vite": "^7.3.5"
+    "vite": "^8.2.2"
   },
   "browserslist": [
     "> 1%",
@@ -96,5 +92,8 @@
     "/src",
     "/dist"
   ],
-  "packageManager": "yarn@4.9.2"
+  "packageManager": "yarn@4.15.0",
+  "engines": {
+    "node": ">=20.0.0"
+  }
 }

package/src/AuthToken.js

@@ -83,6 +83,26 @@ export default class AuthToken {
     return authToken
   }
 
+  /**
+   * ML-KEM parameter set a restored session must use, resolved in three tiers:
+   * an explicit snapshot field, then the stored validator key's length, then ML-KEM-768.
+   *
+   * The final tier is deliberately NOT the constructor default. A snapshot with neither an
+   * explicit field nor a recognisable key can only have come from a pre-bump build, and every
+   * pre-bump build was 768-only — defaulting to 1024 would make the restored wallet advertise
+   * a public key the validator never recorded for that token.
+   *
+   * @param {object} snapshot
+   * @return {number}
+   */
+  static resolveMlKemParameterSet (snapshot) {
+    const explicit = snapshot.wallet && snapshot.wallet.mlKemParameterSet
+    if (explicit) {
+      return Number(explicit)
+    }
+    return Wallet.mlKemParameterSetFromPubkey(snapshot.pubkey) || 768
+  }
+
   /**
    *
    * @param {object} snapshot
@@ -94,7 +114,8 @@ export default class AuthToken {
       secret,
       token: 'AUTH',
       position: snapshot.wallet.position,
-      characters: snapshot.wallet.characters
+      characters: snapshot.wallet.characters,
+      mlKemParameterSet: AuthToken.resolveMlKemParameterSet(snapshot)
     })
     return AuthToken.create({
       token: snapshot.token,
@@ -122,7 +143,7 @@ export default class AuthToken {
 
   /**
    *
-   * @return {{wallet: {characters, position}, encrypt, expiresAt, token, pubkey}}
+   * @return {{wallet: {characters, position, mlKemParameterSet}, encrypt, expiresAt, token, pubkey}}
    */
   getSnapshot () {
     return {
@@ -132,7 +153,8 @@ export default class AuthToken {
       encrypt: this.$__encrypt,
       wallet: {
         position: this.$__wallet.position,
-        characters: this.$__wallet.characters
+        characters: this.$__wallet.characters,
+        mlKemParameterSet: this.$__wallet.mlKemParameterSet
       }
     }
   }

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,9 @@ export default class KnishIOClient {
     socket = null,
     serverSdkVersion = 3,
     logging = false,
-    defaultRequestPolicy = null
+    defaultRequestPolicy = null,
+    secretStorage = null,
+    mlKemParameterSet = 1024
   }) {
     this.initialize({
       uri,
@@ -136,7 +139,9 @@ export default class KnishIOClient {
       client,
       serverSdkVersion,
       logging,
-      defaultRequestPolicy
+      defaultRequestPolicy,
+      secretStorage,
+      mlKemParameterSet
     })
   }
 
@@ -157,15 +162,19 @@ export default class KnishIOClient {
     client = null,
     serverSdkVersion = 3,
     logging = false,
-    defaultRequestPolicy = null
+    defaultRequestPolicy = null,
+    secretStorage = null,
+    mlKemParameterSet = 1024
   }) {
     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
     // a stale cache-first read; browser/SPA consumers leave this null (cache-first).
     this.$__defaultRequestPolicy = defaultRequestPolicy
+    this.setMlKemParameterSet(mlKemParameterSet)
     this.$__authTokenObjects = {}
     this.$__authInProcess = false
     this.abortControllers = new Map()
@@ -197,6 +206,30 @@ export default class KnishIOClient {
     this.$__serverSdkVersion = serverSdkVersion
   }
 
+  /**
+   * Get active ML-KEM parameter set (1024 default or 768 step-back)
+   *
+   * @return {number}
+   */
+  getMlKemParameterSet () {
+    return this.$__mlKemParameterSet || 1024
+  }
+
+  /**
+   * Set active ML-KEM parameter set (1024 default or 768 step-back)
+   *
+   * @param {number|string} parameterSet
+   * @return {KnishIOClient}
+   */
+  setMlKemParameterSet (parameterSet) {
+    const paramNum = Number(parameterSet)
+    if (![1024, 768].includes(paramNum)) {
+      throw new Error(`KnishIO: unsupported ML-KEM parameter set ${parameterSet}; expected 1024 or 768.`)
+    }
+    this.$__mlKemParameterSet = paramNum
+    return this
+  }
+
   /**
    * Get random uri from specified this.$__uris
    *
@@ -278,6 +311,7 @@ export default class KnishIOClient {
   reset () {
     this.$__secret = ''
     this.$__bundle = ''
+    this.$__secretStorage = null
     this.remainderWallet = null
     this.$__capabilityCache = {}
     this.$__defaultRequestPolicy = null
@@ -376,7 +410,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 +421,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 +453,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
    *
@@ -458,7 +537,8 @@ export default class KnishIOClient {
 
     if (!sourceWallet) {
       sourceWallet = new Wallet({
-        secret: this.getSecret()
+        secret: this.getSecret(),
+        mlKemParameterSet: this.getMlKemParameterSet()
       })
     } else {
       sourceWallet.key = Wallet.generateKey({
@@ -496,10 +576,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.
@@ -541,16 +627,19 @@ export default class KnishIOClient {
       bundle,
       token: 'USER',
       batchId: sourceWallet.batchId,
-      characters: sourceWallet.characters
+      characters: sourceWallet.characters,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     return new Molecule({
       secret,
+      bundle,
       sourceWallet,
       remainderWallet: this.getRemainderWallet(),
       cellSlug: this.getCellSlug(),
       version: this.getServerSdkVersion(),
-      continuIdPosition
+      continuIdPosition,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
   }
 
@@ -611,8 +700,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
       })
@@ -1178,7 +1268,8 @@ export default class KnishIOClient {
   }) {
     const newWallet = new Wallet({
       secret: this.getSecret(),
-      token
+      token,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     /**
@@ -1310,7 +1401,8 @@ export default class KnishIOClient {
       secret: this.getSecret(),
       bundle: this.getBundle(),
       token,
-      batchId
+      batchId,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     /**
@@ -1724,7 +1816,8 @@ export default class KnishIOClient {
         } else {
           to = Wallet.create({
             secret: to,
-            token
+            token,
+            mlKemParameterSet: this.getMlKemParameterSet()
           })
         }
       }
@@ -1876,7 +1969,8 @@ export default class KnishIOClient {
     // Attempt to get the recipient's wallet, if not provided
     const recipientWallet = Wallet.create({
       bundle: bundleHash,
-      token
+      token,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     // Compute the batch ID for the recipient
@@ -1976,7 +2070,8 @@ export default class KnishIOClient {
     const recipientWallets = recipients.map(recipient => {
       const recipientWallet = Wallet.create({
         bundle: recipient.bundleHash,
-        token
+        token,
+        mlKemParameterSet: this.getMlKemParameterSet()
       })
 
       // Compute the batch ID for the recipient (typically used by stackable tokens)
@@ -2275,7 +2370,8 @@ export default class KnishIOClient {
     // Generate new recipient wallet if only recipient secret has been passed
     const recipientWallet = Wallet.create({
       bundle: bundleHash,
-      token: tokenSlug
+      token: tokenSlug,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     // Set batch ID
@@ -2331,7 +2427,8 @@ export default class KnishIOClient {
     // Create a wallet for encryption
     const wallet = new Wallet({
       secret: generateSecret(await this.getFingerprint()),
-      token: 'AUTH'
+      token: 'AUTH',
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     /**
@@ -2384,7 +2481,8 @@ export default class KnishIOClient {
     // Generate a signing wallet
     const wallet = new Wallet({
       secret,
-      token: 'AUTH'
+      token: 'AUTH',
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     // Create a wallet with a signing wallet
@@ -2401,7 +2499,7 @@ export default class KnishIOClient {
       molecule
     })
 
-    // PQ-transport Phase E (cycle 163): convey the AUTH source wallet's ML-KEM768 public key as a
+    // PQ-transport Phase E (cycle 163): convey the AUTH source wallet's ML-KEM public key as a
     // SIGNED `walletPubkey` meta on the U-atom (fillMolecule → initAuthorization → sign), so the
     // validator can encrypt CipherHash responses back to THIS wallet (the one that decrypts them).
     // Signed → tamper-proof. Only when present (PQ-capable wallet).
@@ -2464,6 +2562,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

@@ -87,8 +87,10 @@ export default class Molecule {
     remainderWallet = null,
     cellSlug = null,
     version = null,
-    continuIdPosition = null
+    continuIdPosition = null,
+    mlKemParameterSet = null
   }) {
+    this.mlKemParameterSet = mlKemParameterSet || (sourceWallet && sourceWallet.mlKemParameterSet) || 1024
     this.status = null
     this.molecularHash = null
     this.createdAt = String(+new Date())
@@ -110,7 +112,8 @@ export default class Molecule {
         bundle,
         token: sourceWallet.token,
         batchId: sourceWallet.batchId,
-        characters: sourceWallet.characters
+        characters: sourceWallet.characters,
+        mlKemParameterSet: this.mlKemParameterSet
       })
     }
   }
@@ -343,7 +346,8 @@ export default class Molecule {
     if (!this.remainderWallet || this.remainderWallet.token !== 'USER') {
       this.remainderWallet = Wallet.create({
         secret: this.secret,
-        bundle: this.bundle
+        bundle: this.bundle,
+        mlKemParameterSet: this.mlKemParameterSet
       })
     }
 
@@ -479,7 +483,8 @@ export default class Molecule {
     // Create burn address wallet (null bundle = token destruction)
     const burnWallet = new Wallet({
       bundle: '0000000000000000000000000000000000000000000000000000000000000000',
-      token: this.sourceWallet.token
+      token: this.sourceWallet.token,
+      mlKemParameterSet: this.mlKemParameterSet
     })
 
     // V-atom 1: Debit full balance from source
@@ -685,7 +690,8 @@ export default class Molecule {
       secret: this.secret,
       bundle: this.bundle,
       token: this.sourceWallet.token,
-      batchId: this.sourceWallet.batchId
+      batchId: this.sourceWallet.batchId,
+      mlKemParameterSet: this.mlKemParameterSet
     })
     bufferWallet.tradeRates = tradeRates
 
@@ -1080,7 +1086,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()
@@ -1329,7 +1335,8 @@ export default class Molecule {
             position: data.sourceWallet.position,
             bundle: data.sourceWallet.bundle,
             batchId: data.sourceWallet.batchId,
-            characters: data.sourceWallet.characters
+            characters: data.sourceWallet.characters,
+            mlKemParameterSet: molecule.mlKemParameterSet
           })
 
           // Set additional properties for validation context
@@ -1351,7 +1358,8 @@ export default class Molecule {
             position: data.remainderWallet.position,
             bundle: data.remainderWallet.bundle,
             batchId: data.remainderWallet.batchId,
-            characters: data.remainderWallet.characters
+            characters: data.remainderWallet.characters,
+            mlKemParameterSet: molecule.mlKemParameterSet
           })
 
           // Set additional properties for validation context