@wishknish/knishio-client-js 0.9.3 → 1.0.0

package/src/Wallet.js

@@ -59,7 +59,13 @@ import {
 } from './libraries/crypto.js'
 import TokenUnit from './TokenUnit.js'
 import WalletCredentialException from './exception/WalletCredentialException.js'
-import { ml_kem768 as MlKEM768 } from '@noble/post-quantum/ml-kem.js'
+import { ml_kem768 as MlKEM768, ml_kem1024 as MlKEM1024 } from '@noble/post-quantum/ml-kem.js'
+
+const ML_KEM_PARAMS = {
+  1024: { kem: MlKEM1024, pkBytes: 1568, skBytes: 3168, ctBytes: 1568 },
+  768: { kem: MlKEM768, pkBytes: 1184, skBytes: 2400, ctBytes: 1088 }
+}
+const DEFAULT_ML_KEM_PARAMETER_SET = 1024
 
 /**
  * Wallet class represents the set of public and private
@@ -84,8 +90,14 @@ export default class Wallet {
     address = null,
     position = null,
     batchId = null,
-    characters = null
+    characters = null,
+    mlKemParameterSet = DEFAULT_ML_KEM_PARAMETER_SET
   }) {
+    const paramSetNum = Number(mlKemParameterSet)
+    if (!ML_KEM_PARAMS[paramSetNum]) {
+      throw new Error(`KnishIO: unsupported ML-KEM parameter set ${mlKemParameterSet}; expected 1024 or 768.`)
+    }
+    this.mlKemParameterSet = paramSetNum
     this.token = token
     this.balance = '0'
     this.molecules = {}
@@ -141,7 +153,8 @@ export default class Wallet {
     bundle = null,
     token,
     batchId = null,
-    characters = null
+    characters = null,
+    mlKemParameterSet = DEFAULT_ML_KEM_PARAMETER_SET
   }) {
     let position = null
 
@@ -163,7 +176,8 @@ export default class Wallet {
       token,
       position,
       batchId,
-      characters
+      characters,
+      mlKemParameterSet
     })
   }
 
@@ -280,23 +294,49 @@ export default class Wallet {
   }
 
   /**
-   * Initializes the ML-KEM key pair
+   * Derive an ML-KEM keypair for an arbitrary parameter set from the wallet's key seed.
+   *
+   * Returns `null` when the wallet holds no key — a secret-less wallet, which is what
+   * {@link Molecule.fromJSON} builds for validation context. `generateSecret(null, …)` does NOT
+   * throw, so without this the wallet would derive a plausible-looking identity from a bogus seed
+   * and fail three layers down at AES-GCM instead of at the missing key. The guard lives here
+   * rather than at each call site so a new caller cannot miss it.
+   *
+   * @param {number} parameterSet - 1024 or 768
+   * @return {{pubkey: string, privkey: Uint8Array, params: object}|null}
    */
-  initializeMLKEM () {
-    // Generate a 64-byte (512-bit) seed from the Knish.IO private key
-    // Use deterministic approach: generateSecret(key, 128) → 128 hex chars = 64 bytes
+  _deriveMlKemKeypair (parameterSet) {
+    const params = ML_KEM_PARAMS[parameterSet]
+    if (!params) {
+      throw new Error(`KnishIO: unsupported ML-KEM parameter set ${parameterSet}; expected 1024 or 768.`)
+    }
+    if (!this.key) {
+      return null
+    }
     const seedHex = generateSecret(this.key, 128) // 128 hex chars = 64 bytes
-
-    // Convert the hex string to a Uint8Array
     const seed = new Uint8Array(64)
     for (let i = 0; i < 64; i++) {
       seed[i] = parseInt(seedHex.substr(i * 2, 2), 16)
     }
+    const { publicKey, secretKey } = params.kem.keygen(seed)
+    return {
+      pubkey: this.serializeKey(publicKey),
+      privkey: secretKey,
+      params
+    }
+  }
 
-    const { publicKey, secretKey } = MlKEM768.keygen(seed)
-
-    this.pubkey = this.serializeKey(publicKey)
-    this.privkey = secretKey // Note: We're keeping privkey as UInt8Array for security
+  /**
+   * Initializes the ML-KEM key pair. Only ever reached from the constructor's `secret` branch,
+   * so the derivation cannot come back empty here.
+   */
+  initializeMLKEM () {
+    const derived = this._deriveMlKemKeypair(this.mlKemParameterSet)
+    if (!derived) {
+      return
+    }
+    this.pubkey = derived.pubkey
+    this.privkey = derived.privkey
   }
 
   serializeKey (key) {
@@ -321,6 +361,35 @@ export default class Wallet {
     return new Uint8Array(binaryString.length).map((_, i) => binaryString.charCodeAt(i))
   }
 
+  /**
+   * ML-KEM parameter set implied by a serialized public key's raw byte length. FIPS 203's
+   * key lengths are disjoint (1568 bytes → ML-KEM-1024, 1184 bytes → ML-KEM-768), so a stored
+   * peer key recovers the parameter set of the session it belongs to without a wire-format
+   * change. Used by {@link AuthToken.restore} to resolve a snapshot that predates the field.
+   *
+   * @param {string|null} pubkey - Base64-serialized ML-KEM public key
+   * @return {number|null} 1024, 768, or null when the length matches neither
+   */
+  static mlKemParameterSetFromPubkey (pubkey) {
+    if (!pubkey) {
+      return null
+    }
+    let byteLength
+    try {
+      byteLength = typeof Buffer !== 'undefined'
+        ? Buffer.from(pubkey, 'base64').length
+        : atob(pubkey).length
+    } catch (e) {
+      return null
+    }
+    for (const [set, params] of Object.entries(ML_KEM_PARAMS)) {
+      if (params.pkBytes === byteLength) {
+        return Number(set)
+      }
+    }
+    return null
+  }
+
   /**
    * Returns balance as a Number for arithmetic operations.
    * WARNING: Precision loss for values > 2^53.
@@ -499,19 +568,19 @@ export default class Wallet {
     const messageString = JSON.stringify(message)
     const messageUint8 = new TextEncoder().encode(messageString)
     const deserializedPubkey = this.deserializeKey(recipientPubkey)
-    // ML-KEM-768 public keys are exactly 1184 bytes. A wrong-length key here almost always means the
-    // node did not advertise an ML-KEM public key in its auth `key` field (e.g. a validator predating
-    // the PQ-transport build). Fail with an actionable message rather than the crypto lib's cryptic
-    // `"publicKey" expected Uint8Array of length 1184, got length=N` assertion.
-    const ML_KEM_768_PUBLIC_KEY_BYTES = 1184
-    if (deserializedPubkey.length !== ML_KEM_768_PUBLIC_KEY_BYTES) {
+    // ML-KEM public keys are exactly 1568 bytes (ML-KEM-1024) or 1184 bytes (ML-KEM-768). A wrong-length key here
+    // almost always means the node did not advertise an ML-KEM public key in its auth `key` field (e.g. a validator
+    // predating the PQ-transport build). Fail with an actionable message rather than the crypto lib's cryptic
+    // `"publicKey" expected Uint8Array of length N, got length=M` assertion.
+    const params = ML_KEM_PARAMS[this.mlKemParameterSet]
+    if (deserializedPubkey.length !== params.pkBytes) {
       throw new Error(
         `KnishIO: cannot ML-KEM-encrypt — recipient public key is ${deserializedPubkey.length} bytes, ` +
-        `expected ${ML_KEM_768_PUBLIC_KEY_BYTES} (ML-KEM-768). The node likely did not advertise an ML-KEM ` +
-        'public key (upgrade the validator to a PQ-transport build), or authenticate with { encrypt: false }.'
+        `expected ${params.pkBytes} (ML-KEM-${this.mlKemParameterSet}). The peer is not running ML-KEM-${this.mlKemParameterSet}; ` +
+        'upgrade the peer, or step this client back to the other parameter set.'
       )
     }
-    const { cipherText, sharedSecret } = MlKEM768.encapsulate(deserializedPubkey)
+    const { cipherText, sharedSecret } = params.kem.encapsulate(deserializedPubkey)
     const encryptedMessage = await this.encryptWithSharedSecret(messageUint8, sharedSecret)
     return {
       cipherText: this.serializeKey(cipherText),
@@ -525,17 +594,46 @@ export default class Wallet {
   }
 
   /**
-   * ML-KEM768 decapsulate + AES-256-GCM decrypt → the RAW decrypted UTF-8 string
+   * ML-KEM decapsulate + AES-256-GCM decrypt → the RAW decrypted UTF-8 string
    * (no JSON.parse). Shared by {@link decryptMessage} (which JSON.parses the result)
-   * and the PQ CipherHash transport ({@link decryptMyMessageML768}, which needs the raw
+   * and the PQ CipherHash transport ({@link decryptMyMessageML}, which needs the raw
    * response JSON text). PQ-transport Phase E (cycle 163).
    */
   async _mlkemDecryptToString (encryptedData) {
     const { cipherText, encryptedMessage } = encryptedData
 
+    const deserializedCipherText = this.deserializeKey(cipherText)
+    const configuredParams = ML_KEM_PARAMS[this.mlKemParameterSet]
+    const otherSet = this.mlKemParameterSet === 1024 ? 768 : 1024
+
+    // Inbound is PERMISSIVE: a ciphertext at either parameter set decrypts, provided it is addressed
+    // to one of THIS wallet's own ML-KEM identities. The 64-byte seed is parameter-set-independent,
+    // so the other identity is derived on demand and its private key is released with this call's
+    // scope — never cached on the wallet. Outbound encapsulation stays STRICT (see encryptMessage);
+    // reading a 768 record we own downgrades nothing, but encapsulating at 768 would.
+    let decapsParams = configuredParams
+    let decapsPrivkey = this.privkey
+    if (deserializedCipherText.length !== configuredParams.ctBytes) {
+      if (deserializedCipherText.length !== ML_KEM_PARAMS[otherSet].ctBytes) {
+        console.error(
+          `Wallet::decryptMessage() - Ciphertext length mismatch: got ${deserializedCipherText.length}, expected ${configuredParams.ctBytes}`
+        )
+        return null
+      }
+      // `null` here means the wallet holds no key to derive from (a secret-less validation
+      // wallet); preserve the existing failure observable rather than decapsulating with nothing.
+      const derived = this._deriveMlKemKeypair(otherSet)
+      if (!derived) {
+        console.error(`Wallet::decryptMessage() - cannot derive the ML-KEM-${otherSet} identity: wallet has no key`)
+        return null
+      }
+      decapsParams = derived.params
+      decapsPrivkey = derived.privkey
+    }
+
     let sharedSecret
     try {
-      sharedSecret = MlKEM768.decapsulate(this.deserializeKey(cipherText), this.privkey)
+      sharedSecret = decapsParams.kem.decapsulate(deserializedCipherText, decapsPrivkey)
     } catch (e) {
       console.error('Wallet::decryptMessage() - Decapsulation failed', e)
       console.info('Wallet::decryptMessage() - my public key', this.pubkey)
@@ -587,11 +685,11 @@ export default class Wallet {
   }
 
   /**
-   * Post-quantum (ML-KEM768) `CipherHash` request envelope: a stringified single-recipient
+   * Post-quantum (ML-KEM) `CipherHash` request envelope: a stringified single-recipient
    * map `{ "<hashShare(recipientPubkey)>": {cipherText, encryptedMessage} }` (object-valued,
    * via {@link encryptMessage}). Matches the Rust validator's CipherHash handler. PQ Phase E.
    */
-  async encryptStringML768 (message, recipientPubkey) {
+  async encryptStringML (message, recipientPubkey) {
     const envelope = await this.encryptMessage(message, recipientPubkey)
     return JSON.stringify({ [this.hashShare(recipientPubkey)]: envelope })
   }
@@ -601,8 +699,17 @@ export default class Wallet {
    * (`hashShare(this.pubkey)`) → the RAW decrypted GraphQL response JSON text (NOT JSON.parsed;
    * it replaces the HTTP response body for the normal parser). `null` if no entry / decrypt fails.
    */
-  async decryptMyMessageML768 (map) {
-    const envelope = map[this.hashShare(this.pubkey)]
+  async decryptMyMessageML (map) {
+    let envelope = map[this.hashShare(this.pubkey)]
+    if (!envelope) {
+      // Inbound permissive: try the hash share of the on-demand derived other-set pubkey.
+      // A secret-less wallet derives nothing, so the lookup is simply skipped.
+      const otherSet = this.mlKemParameterSet === 1024 ? 768 : 1024
+      const other = this._deriveMlKemKeypair(otherSet)
+      if (other) {
+        envelope = map[this.hashShare(other.pubkey)]
+      }
+    }
     if (!envelope) {
       return null
     }

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/libraries/urql/UrqlClientWrapper.js

@@ -63,6 +63,11 @@ class UrqlClientWrapper {
     return createClient({
       url: serverUri,
       exchanges,
+      // 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,
       // 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). Undefined → urql uses the global fetch (plaintext).
@@ -114,7 +119,7 @@ class UrqlClientWrapper {
     let requestInit = init
 
     if (wallet && serverPubkey && init && typeof init.body === 'string' && this.shouldEncrypt(init.body)) {
-      const hashVar = await wallet.encryptStringML768(init.body, serverPubkey)
+      const hashVar = await wallet.encryptStringML(init.body, serverPubkey)
       requestInit = { ...init, body: JSON.stringify({ query: CIPHER_HASH_QUERY, variables: { Hash: hashVar } }) }
       encryptedRequest = true
     }
@@ -138,7 +143,7 @@ class UrqlClientWrapper {
       // Plaintext (e.g. a validator-side error response) — pass through unchanged.
       return new Response(text, init2)
     }
-    const decrypted = await wallet.decryptMyMessageML768(JSON.parse(hash))
+    const decrypted = await wallet.decryptMyMessageML(JSON.parse(hash))
     return new Response(decrypted != null ? decrypted : text, init2)
   }