@wishknish/knishio-client-ts 0.9.7 → 1.0.0

package/src/core/Wallet.ts

@@ -52,8 +52,17 @@ import { generateBundleHash, generateSecret, shake256, generateBatchId } from '@
 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'
+// Post-quantum cryptography for ML-KEM key encapsulation
+import { ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem.js'
+
+const ML_KEM_PARAMS = {
+  1024: { kem: ml_kem1024, pkBytes: 1568, skBytes: 3168, ctBytes: 1568 },
+  768: { kem: ml_kem768, pkBytes: 1184, skBytes: 2400, ctBytes: 1088 }
+} as const
+const DEFAULT_ML_KEM_PARAMETER_SET = 1024
+
+type MlKemParams = (typeof ML_KEM_PARAMS)[1024 | 768]
+type MlKemKeypair = { pubkey: string; privkey: Uint8Array; params: MlKemParams }
 
 /**
  * Wallet class - Identity and key management for KnishIO DLT
@@ -73,6 +82,7 @@ export default class Wallet {
   public tokenUnits: any[]
   public tradeRates: Record<string, any>
   public molecules: Record<string, any>
+  public mlKemParameterSet: 1024 | 768
 
   // Token metadata (populated from query responses)
   public tokenName?: string
@@ -88,7 +98,8 @@ export default class Wallet {
     address = null,
     position = null,
     batchId = null,
-    characters = null
+    characters = null,
+    mlKemParameterSet = DEFAULT_ML_KEM_PARAMETER_SET
   }: {
     secret?: string | null
     bundle?: string | null
@@ -97,7 +108,13 @@ export default class Wallet {
     position?: string | null
     batchId?: string | null
     characters?: string | null
+    mlKemParameterSet?: 1024 | 768
   } = {}) {
+    const paramSetNum = Number(mlKemParameterSet) as 1024 | 768
+    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 = {}
@@ -133,7 +150,7 @@ export default class Wallet {
       // Set characters
       this.characters = this.characters || 'BASE64'
       
-      // Initialize ML-KEM768 keys (matches JavaScript SDK)
+      // Initialize ML-KEM keys (matches JavaScript SDK)
       this.initializeMLKEM()
     }
   }
@@ -147,13 +164,15 @@ export default class Wallet {
     bundle = null,
     token = 'USER',
     batchId = null,
-    characters = null
+    characters = null,
+    mlKemParameterSet = DEFAULT_ML_KEM_PARAMETER_SET
   }: {
     secret?: string | null
     bundle?: string | null
     token?: string
     batchId?: string | null
     characters?: string | null
+    mlKemParameterSet?: 1024 | 768
   }): Wallet {
     let position: string | null = null
 
@@ -176,7 +195,8 @@ export default class Wallet {
       token,
       position,
       batchId,
-      characters
+      characters,
+      mlKemParameterSet
     })
   }
 
@@ -408,26 +428,90 @@ export default class Wallet {
   }
 
   // =============================================================================
-  // POST-QUANTUM CRYPTOGRAPHY - ML-KEM768 INTEGRATION
+  // POST-QUANTUM CRYPTOGRAPHY - ML-KEM INTEGRATION
   // =============================================================================
 
   /**
-   * Initializes the ML-KEM key pair (matches JavaScript SDK exactly)
+   * Derive an ML-KEM keypair for an arbitrary parameter set from the wallet's key seed,
+   * without mutating the wallet. The 64-byte `d‖z` seed takes no parameter-set input — only
+   * the final `keygen` call differs — so one KnishIO wallet owns both an ML-KEM-768 and an
+   * ML-KEM-1024 identity and either can be reconstructed on demand.
+   *
+   * Returns `null` when the wallet holds no key — a secret-less wallet, which is what a molecule
+   * deserializer 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 parameterSet - 1024 or 768
    */
-  initializeMLKEM(): void {
+  private deriveMlKemKeypair(parameterSet: 1024 | 768): MlKemKeypair | null {
+    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
+    }
     // Generate a 64-byte (512-bit) seed from the Knish.IO private key
     // Use deterministic approach: generateSecret(key, 128) → 128 hex chars = 64 bytes
-    const seedHex = generateSecret(this.key!, 128)  // 128 hex chars = 64 bytes, matches JS SDK
-    
-    // Convert the hex string to a Uint8Array  
+    const seedHex = generateSecret(this.key, 128)  // 128 hex chars = 64 bytes, matches JS SDK
+
+    // 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 } = ml_kem768.keygen(seed)
-    this.pubkey = this.serializeKey(publicKey)
-    this.privkey = secretKey // Note: We're keeping privkey as UInt8Array for security
+
+    const { publicKey, secretKey } = params.kem.keygen(seed)
+    return {
+      pubkey: this.serializeKey(publicKey),
+      privkey: secretKey,
+      params
+    }
+  }
+
+  /**
+   * 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 AuthToken.restore to resolve a snapshot that predates the field.
+   *
+   * @param pubkey - Base64-serialized ML-KEM public key
+   * @return 1024, 768, or null when the length matches neither
+   */
+  static mlKemParameterSetFromPubkey(pubkey: string | null | undefined): 1024 | 768 | null {
+    if (!pubkey) {
+      return null
+    }
+    let byteLength: number
+    try {
+      byteLength = typeof Buffer !== 'undefined'
+        ? Buffer.from(pubkey, 'base64').length
+        : atob(pubkey).length
+    } catch {
+      return null
+    }
+    if (byteLength === ML_KEM_PARAMS[1024].pkBytes) {
+      return 1024
+    }
+    if (byteLength === ML_KEM_PARAMS[768].pkBytes) {
+      return 768
+    }
+    return null
+  }
+
+  /**
+   * Initializes the ML-KEM key pair (matches JavaScript SDK exactly). Only ever reached from the
+   * constructor's `secret` branch, so the derivation cannot come back empty here.
+   */
+  initializeMLKEM(): void {
+    const derived = this.deriveMlKemKeypair(this.mlKemParameterSet)
+    if (!derived) {
+      return
+    }
+    this.pubkey = derived.pubkey
+    this.privkey = derived.privkey // Note: We're keeping privkey as UInt8Array for security
   }
 
 
@@ -439,19 +523,20 @@ 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 @noble'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 the configured parameter set's length — 1568 bytes for
+    // ML-KEM-1024, 1184 bytes for 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 @noble'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 } = ml_kem768.encapsulate(deserializedPubkey)
+    const { cipherText, sharedSecret } = params.kem.encapsulate(deserializedPubkey)
     const encryptedMessage = await this.encryptWithSharedSecret(messageUint8, sharedSecret)
     return {
       cipherText: this.serializeKey(cipherText),
@@ -465,15 +550,46 @@ export default class Wallet {
   }
 
   /**
-   * ML-KEM768 decapsulate + AES-256-GCM decrypt → the RAW decrypted UTF-8 string (no JSON.parse).
+   * 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 response JSON text). PQ-transport Phase E.
+   * ({@link decryptMyMessageML}, which needs the raw response JSON text). PQ-transport Phase E.
    */
   async _mlkemDecryptToString(encryptedData: { cipherText: string; encryptedMessage: string }): Promise<string | null> {
     const { cipherText, encryptedMessage } = encryptedData
+    const configuredParams = ML_KEM_PARAMS[this.mlKemParameterSet]
+    const otherSet: 1024 | 768 = this.mlKemParameterSet === 1024 ? 768 : 1024
+    const deserializedCipherText = this.deserializeKey(cipherText)
+
+    // 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 params: MlKemParams = configuredParams
+    let decapsPrivkey: Uint8Array = 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
+      }
+      params = derived.params
+      decapsPrivkey = derived.privkey
+    }
+
     let sharedSecret
     try {
-      sharedSecret = ml_kem768.decapsulate(this.deserializeKey(cipherText), this.privkey)
+      sharedSecret = params.kem.decapsulate(deserializedCipherText, decapsPrivkey)
     } catch (e) {
       console.error('Wallet::decryptMessage() - Decapsulation failed', e)
       console.info('Wallet::decryptMessage() - my public key', this.pubkey)
@@ -525,11 +641,11 @@ export default class Wallet {
   }
 
   /**
-   * Post-quantum (ML-KEM768) CipherHash request envelope: a stringified single-recipient map
+   * 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-transport Phase E.
    */
-  async encryptStringML768(message: any, recipientPubkey: string): Promise<string> {
+  async encryptStringML(message: any, recipientPubkey: string): Promise<string> {
     const envelope = await this.encryptMessage(message, recipientPubkey)
     return JSON.stringify({ [this.hashShare(recipientPubkey)]: envelope })
   }
@@ -538,9 +654,22 @@ export default class Wallet {
    * Decrypt a CipherHash response map addressed to THIS wallet's ML-KEM pubkey
    * (`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.
+   *
+   * A pre-bump peer addressed its envelope to `hashShare(our_768_pubkey)`, which a wallet
+   * configured at ML-KEM-1024 would never find — so the other identity's share is tried too.
+   * Without this, the permissive length dispatch in {@link _mlkemDecryptToString} is
+   * unreachable on the transport path.
    */
-  async decryptMyMessageML768(map: Record<string, { cipherText: string; encryptedMessage: string }>): Promise<string | null> {
-    const envelope = map[this.hashShare(this.pubkey)]
+  async decryptMyMessageML(map: Record<string, { cipherText: string; encryptedMessage: string }>): Promise<string | null> {
+    let envelope = map[this.hashShare(this.pubkey)]
+    if (!envelope) {
+      // A secret-less wallet derives nothing, so the lookup is simply skipped.
+      const otherSet: 1024 | 768 = this.mlKemParameterSet === 1024 ? 768 : 1024
+      const other = this.deriveMlKemKeypair(otherSet)
+      if (other) {
+        envelope = map[this.hashShare(other.pubkey)]
+      }
+    }
     if (!envelope) {
       return null
     }

package/src/index.ts

@@ -389,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.7'
+export const SDK_VERSION = '1.0.0'
 export const SDK_NAME = 'KnishIO-Client-TS'
 export const COMPATIBLE_SERVER_VERSIONS = [4, 5]
 
@@ -402,7 +402,7 @@ export const SDK_INFO = {
   description: 'TypeScript SDK for Knish.IO post-blockchain distributed ledger',
   compatibleServerVersions: COMPATIBLE_SERVER_VERSIONS,
   features: [
-    'Post-quantum cryptography (XMSS, ML-KEM768)',
+    'Post-quantum cryptography (XMSS, ML-KEM-1024)',
     'Cross-platform compatibility',
     'Type-safe APIs',
     'DAG-based transaction processing',

package/src/libraries/GraphQLClient.ts

@@ -204,7 +204,7 @@ export default class GraphQLClient implements IGraphQLClient {
     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
     }
@@ -228,7 +228,7 @@ export default class GraphQLClient implements IGraphQLClient {
       // 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)
   }
 

package/src/mutation/MutationProposeMolecule.ts

@@ -57,7 +57,7 @@ import type Molecule from '../core/Molecule'
  * MutationProposeMolecule - Foundation for all molecular proposals
  * Matches JavaScript SDK MutationProposeMolecule implementation exactly
  */
-export default abstract class MutationProposeMolecule extends Mutation {
+export default class MutationProposeMolecule extends Mutation {
   protected $__molecule: Molecule
   protected $__remainderWallet: any | null = null
 
@@ -141,8 +141,11 @@ export default abstract class MutationProposeMolecule extends Mutation {
   }
 
   /**
-   * Abstract method to be implemented by subclasses
-   * Fills the molecule with specific mutation data
+   * Fills the molecule with specific mutation data.
+   * Subclasses override to build domain-specific atoms.
+   * Default implementation is a no-op for pre-assembled molecules.
    */
-  abstract fillMolecule(params: any): void
+  fillMolecule(_params?: any): void {
+    // Intentionally empty for pre-assembled molecules proposed directly
+  }
 }

package/src/schemas/index.ts

@@ -208,7 +208,8 @@ export const KnishIOClientConfigSchema = z.object({
   serverSdkVersion: z.number().int().min(1).optional(),
   logging: z.boolean().optional(),
   defaultRequestPolicy: z.enum(['cache-first', 'cache-only', 'network-only', 'cache-and-network']).nullable().optional(),
-  secretStorage: z.unknown().optional()
+  secretStorage: z.unknown().optional(),
+  mlKemParameterSet: z.union([z.literal(1024), z.literal(768)]).optional()
 }).strict()
 
 // =============================================================================

package/src/types/crypto.ts

@@ -58,8 +58,8 @@ import type { WalletAddress, BundleHash, Position, TokenSlug } from './index'
 // =============================================================================
 
 export type HashAlgorithm = 'SHAKE256' | 'SHA3-256' | 'BLAKE2B'
-export type SignatureAlgorithm = 'XMSS' | 'ML-KEM768' | 'SPHINCS+'
-export type EncryptionAlgorithm = 'ML-KEM768' | 'Kyber768' | 'ChaCha20Poly1305'
+export type SignatureAlgorithm = 'XMSS' | 'SPHINCS+'
+export type EncryptionAlgorithm = 'ML-KEM-1024' | 'ML-KEM-768'
 
 // =============================================================================
 // SHAKE256 SPECIFIC TYPES
@@ -139,13 +139,13 @@ export interface XMSSSignature {
 }
 
 // =============================================================================
-// ML-KEM768 (Post-Quantum Key Encapsulation) TYPES
+// ML-KEM (Post-Quantum Key Encapsulation) TYPES
 // =============================================================================
 
 export interface MLKEMKeyPair {
   privateKey: Uint8Array
   publicKey: Uint8Array
-  algorithm: 'ML-KEM768'
+  algorithm: EncryptionAlgorithm
 }
 
 export interface MLKEMEncapsulationResult {
@@ -475,6 +475,11 @@ export const CRYPTO_CONSTANTS = {
   ML_KEM768_PRIVATE_KEY_SIZE: 2400,
   ML_KEM768_CIPHERTEXT_SIZE: 1088,
   ML_KEM768_SHARED_SECRET_SIZE: 32,
+
+  ML_KEM1024_PUBLIC_KEY_SIZE: 1568,
+  ML_KEM1024_PRIVATE_KEY_SIZE: 3168,
+  ML_KEM1024_CIPHERTEXT_SIZE: 1568,
+  ML_KEM1024_SHARED_SECRET_SIZE: 32,
   
   KEY_FRAGMENT_SIZE: 128,
   OTS_FRAGMENT_COUNT: 16,

package/src/validation/schemas.ts

@@ -231,7 +231,8 @@ export const KnishIOClientConfigSchema = z.object({
   // isn't rejected.
   defaultRequestPolicy: z.enum(['cache-first', 'cache-only', 'network-only', 'cache-and-network']).nullable().optional(),
   // Pluggable hardware envelope encryption secret storage provider
-  secretStorage: z.unknown().optional()
+  secretStorage: z.unknown().optional(),
+  mlKemParameterSet: z.union([z.literal(1024), z.literal(768)]).optional()
 }).strict()
 
 // Environment configuration with validation.