@wishknish/knishio-client-ts 0.9.8 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.9.8",
+  "version": "1.0.0",
   "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",
@@ -51,7 +51,7 @@
     "quantum-safe",
     "sdk",
     "typescript",
-    "ml-kem768",
+    "ml-kem1024",
     "cryptography",
     "crystals-kyber",
     "fips-202",
@@ -112,6 +112,6 @@
   ],
   "packageManager": "yarn@4.15.0",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   }
 }

package/src/AuthToken.ts

@@ -48,6 +48,25 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 
 import Wallet from '@/core/Wallet'
 
+/**
+ * Persisted session shape. Shared by {@link AuthToken.restore} and {@link AuthToken.toSnapshot}
+ * so the two can never drift: a field either round-trips or neither side compiles.
+ *
+ * `wallet.mlKemParameterSet` is optional because snapshots persisted before ML-KEM-1024 became
+ * the default do not carry it — see {@link AuthToken.resolveMlKemParameterSet}.
+ */
+export type AuthTokenSnapshot = {
+  token: string
+  expiresAt: number
+  pubkey: string
+  encrypt: boolean
+  wallet?: {
+    position: string | null
+    characters: string | null
+    mlKemParameterSet?: 1024 | 768
+  }
+}
+
 /**
  * AuthToken class for managing authentication tokens
  */
@@ -93,25 +112,34 @@ export default class AuthToken {
   }
 
   /**
-   * Restore AuthToken from snapshot
+   * 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.
    */
-  static restore(snapshot: {
-    token: string
-    expiresAt: number
-    pubkey: string
-    encrypt: boolean
-    wallet: {
-      position: string
-      characters: string | null
+  static resolveMlKemParameterSet(snapshot: AuthTokenSnapshot): 1024 | 768 {
+    const explicit = snapshot.wallet?.mlKemParameterSet
+    if (explicit) {
+      return Number(explicit) === 768 ? 768 : 1024
     }
-  }, secret: string): AuthToken {
+    return Wallet.mlKemParameterSetFromPubkey(snapshot.pubkey) ?? 768
+  }
+
+  /**
+   * Restore AuthToken from snapshot
+   */
+  static restore(snapshot: AuthTokenSnapshot, secret: string): AuthToken {
     const wallet = new Wallet({
       secret,
       token: 'AUTH',
-      position: snapshot.wallet.position,
-      characters: snapshot.wallet.characters
+      position: snapshot.wallet?.position ?? null,
+      characters: snapshot.wallet?.characters ?? null,
+      mlKemParameterSet: AuthToken.resolveMlKemParameterSet(snapshot)
     })
-    
+
     return AuthToken.create({
       token: snapshot.token,
       expiresAt: snapshot.expiresAt,
@@ -192,18 +220,11 @@ export default class AuthToken {
   }
 
   /**
-   * Create snapshot for persistence
+   * Create snapshot for persistence. The wallet's ML-KEM parameter set is recorded beside its
+   * position and characters so a stepped-back ML-KEM-768 session restores as 768 rather than
+   * silently taking the constructor default.
    */
-  toSnapshot(): {
-    token: string
-    expiresAt: number
-    pubkey: string
-    encrypt: boolean
-    wallet?: {
-      position: string | null
-      characters: string | null
-    }
-  } {
+  toSnapshot(): AuthTokenSnapshot {
     return {
       token: this.$__token,
       expiresAt: this.$__expiresAt,
@@ -212,7 +233,8 @@ export default class AuthToken {
       ...(this.$__wallet ? {
         wallet: {
           position: this.$__wallet.position,
-          characters: this.$__wallet.characters
+          characters: this.$__wallet.characters,
+          mlKemParameterSet: this.$__wallet.mlKemParameterSet
         }
       } : {})
     }

package/src/KnishIOClient.ts

@@ -166,6 +166,7 @@ export default class KnishIOClient {
   private $__authTokenObjects: Record<string, AuthToken | null> = {}
   private $__authToken: AuthToken | null = null
   private $__authInProcess: boolean = false
+  private $__mlKemParameterSet: 1024 | 768 = 1024
   private $__remainderWallet: Wallet | null = null
   private lastMoleculeQuery: Mutation | null = null
   private abortControllers: Map<string, AbortController> = new Map()
@@ -189,6 +190,7 @@ export default class KnishIOClient {
     logging?: boolean
     defaultRequestPolicy?: RequestPolicy | null
     secretStorage?: ISecretStorageProvider | null
+    mlKemParameterSet?: 1024 | 768
   }) {
     // Phase 2 Enhancement: Use standardized configuration validation
     const standardValidationResult = ConfigValidator.validateClientConfig(config)
@@ -238,7 +240,8 @@ export default class KnishIOClient {
       client: client as GraphQLClient | null,
       serverSdkVersion,
       logging,
-      defaultRequestPolicy
+      defaultRequestPolicy,
+      mlKemParameterSet: config.mlKemParameterSet ?? 1024
     })
 
     if (config.secretStorage) {
@@ -256,7 +259,8 @@ export default class KnishIOClient {
     client = null,
     serverSdkVersion = 3,
     logging = false,
-    defaultRequestPolicy = null
+    defaultRequestPolicy = null,
+    mlKemParameterSet = 1024
   }: {
     uri: string | string[]
     cellSlug?: string | null
@@ -265,10 +269,12 @@ export default class KnishIOClient {
     serverSdkVersion?: number
     logging?: boolean
     defaultRequestPolicy?: RequestPolicy | null
+    mlKemParameterSet?: 1024 | 768
   }): void {
     this.reset()
 
     this.$__logging = logging
+    this.setMlKemParameterSet(mlKemParameterSet)
     this.$__authTokenObjects = {}
 
     this.setUri(uri)
@@ -297,6 +303,19 @@ export default class KnishIOClient {
     // serverSdkVersion. A re-initialize updates it.
     this.$__defaultRequestPolicy = defaultRequestPolicy
   }
+  getMlKemParameterSet(): 1024 | 768 {
+    return this.$__mlKemParameterSet || 1024
+  }
+
+  setMlKemParameterSet(parameterSet: 1024 | 768): this {
+    const paramNum = Number(parameterSet) as 1024 | 768
+    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
@@ -589,7 +608,8 @@ export default class KnishIOClient {
       bundle,
       token: 'USER',
       batchId: sourceWallet!.batchId,
-      characters: sourceWallet!.characters
+      characters: sourceWallet!.characters,
+      mlKemParameterSet: this.getMlKemParameterSet()
     }))
 
     return new Molecule({
@@ -599,7 +619,8 @@ export default class KnishIOClient {
       remainderWallet: this.getRemainderWallet()!,
       cellSlug: this.getCellSlug(),
       version: this.getServerSdkVersion(),
-      continuIdPosition
+      continuIdPosition,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
   }
 
@@ -756,7 +777,8 @@ export default class KnishIOClient {
 
     if (!sourceWallet) {
       sourceWallet = new Wallet({
-        secret: this.getSecret()
+        secret: this.getSecret(),
+        mlKemParameterSet: this.getMlKemParameterSet()
       })
     } else {
       sourceWallet.key = Wallet.generateKey({
@@ -819,7 +841,8 @@ export default class KnishIOClient {
     // Attempt to get the recipient's wallet
     const recipientWallet = Wallet.create({
       bundle: bundleHash,
-      token
+      token,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     // Compute the batch ID for the recipient (typically used by stackable tokens)
@@ -909,7 +932,8 @@ export default class KnishIOClient {
     const recipientWallets: Wallet[] = recipients.map(recipient => {
       const recipientWallet = Wallet.create({
         bundle: recipient.bundleHash,
-        token
+        token,
+        mlKemParameterSet: this.getMlKemParameterSet()
       })
       if (recipient.batchId !== null && recipient.batchId !== undefined) {
         recipientWallet.batchId = recipient.batchId
@@ -1774,7 +1798,8 @@ export default class KnishIOClient {
       secret: this.getSecret(),
       bundle: this.getBundle(),
       token,
-      batchId: batchId as any
+      batchId: batchId as any,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     // Initialize the create token mutation
@@ -1880,7 +1905,8 @@ export default class KnishIOClient {
     const recipientWallet = new Wallet({
       secret: this.getSecret(),
       bundle: '0000000000000000000000000000000000000000000000000000000000000000',
-      token
+      token,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     await mutation.fillMolecule({
@@ -1993,7 +2019,8 @@ export default class KnishIOClient {
     const newWallet = new Wallet({
       secret: this.getSecret(),
       bundle: this.getBundle(),
-      token
+      token,
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     // Initialize the create wallet mutation
@@ -2499,7 +2526,8 @@ export default class KnishIOClient {
     // Generate a signing wallet with AUTH token (matching JavaScript SDK)
     const wallet = new Wallet({
       secret,
-      token: 'AUTH'
+      token: 'AUTH',
+      mlKemParameterSet: this.getMlKemParameterSet()
     })
 
     // Create a molecule with the AUTH wallet as source
@@ -2515,7 +2543,7 @@ export default class KnishIOClient {
     })
 
     // Initialize the profile auth mutation.
-    // PQ-transport Phase E: convey the AUTH source wallet's ML-KEM768 public key as a SIGNED
+    // PQ-transport Phase E: convey the AUTH source wallet's ML-KEM public key as a SIGNED
     // walletPubkey U-atom meta, so the validator can encrypt CipherHash responses back to THIS
     // wallet (the one that decrypts them). Signed → MITM can't swap the target. Conveyed
     // unconditionally (parity with JS/Kotlin/PHP), so even a plaintext auth primes enc_pubkey.

package/src/core/Molecule.ts

@@ -81,6 +81,7 @@ export default class Molecule {
   public continuIdPosition: string | null
   public parentHashes: string[]
   public local?: number
+  public mlKemParameterSet: 1024 | 768 = 1024
 
   /**
    * Create new Molecule instance
@@ -93,7 +94,8 @@ export default class Molecule {
     remainderWallet = null,
     cellSlug = null,
     version = null,
-    continuIdPosition = null
+    continuIdPosition = null,
+    mlKemParameterSet = null
   }: {
     secret?: string | null
     bundle?: string | null
@@ -102,6 +104,7 @@ export default class Molecule {
     cellSlug?: string | null
     version?: string | number | null
     continuIdPosition?: string | null
+    mlKemParameterSet?: 1024 | 768 | null
   } = {}) {
     this.status = null
     this.molecularHash = null
@@ -113,6 +116,7 @@ export default class Molecule {
     this.continuIdPosition = continuIdPosition
     this.atoms = []
     this.parentHashes = []
+    this.mlKemParameterSet = mlKemParameterSet || sourceWallet?.mlKemParameterSet || 1024
 
     const versionRegistry = versions as Record<string | number, any>
     if (version !== null && Object.prototype.hasOwnProperty.call(versionRegistry, version)) {
@@ -129,7 +133,8 @@ export default class Molecule {
         bundle,
         token: sourceWallet!.token,
         batchId: sourceWallet!.batchId,
-        characters: sourceWallet!.characters
+        characters: sourceWallet!.characters,
+        mlKemParameterSet: this.mlKemParameterSet
       })
     } else {
       this.remainderWallet = null
@@ -206,7 +211,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
       })
     }
 
@@ -724,7 +730,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
@@ -1099,7 +1106,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
@@ -1121,7 +1129,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
@@ -1245,7 +1254,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
     })
     if (tradeRates) {
       bufferWallet.tradeRates = tradeRates