@wishknish/knishio-client-ts 0.8.3 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "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",
@@ -71,23 +71,19 @@
   },
   "devDependencies": {
     "@types/isomorphic-fetch": "^0.0.39",
-    "@types/jest": "^30.0.0",
     "@types/jssha": "^3.0.0",
-    "@types/node": "^22.8.1",
-    "@types/pg": "^8.10.0",
-    "@typescript-eslint/eslint-plugin": "^8.15.0",
-    "@typescript-eslint/parser": "^8.15.0",
-    "eslint": "^9.16.0",
-    "jest": "^30.2.0",
-    "pg": "^8.11.0",
-    "prettier": "^3.4.2",
-    "ts-jest": "^29.4.6",
-    "tsup": "^8.3.5",
-    "tsx": "^4.20.5",
-    "typescript": "^5.6.3",
-    "vite": "^6.3.5",
-    "vite-plugin-dts": "^4.2.3",
-    "vitest": "^2.1.8"
+    "@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",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.0",
+    "typescript": "^5",
+    "vite": "^7",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.1.10"
   },
   "browserslist": [
     "> 1%",
@@ -100,10 +96,12 @@
     "build:test": "tsup src/index.ts --format esm,cjs,iife --tsconfig tsconfig.build.json --clean",
     "build:dev": "tsup src/index.ts --format esm,cjs --dts --sourcemap --watch",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src --ext .ts,.tsx --fix",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
     "format": "prettier --write \"src/**/*.{ts,tsx}\"",
-    "test": "vitest",
-    "test:coverage": "vitest --coverage",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
     "dev": "vite",
     "prepublishOnly": "npm run build",

package/src/KnishIOClient.ts

@@ -50,7 +50,8 @@ import Decimal from '@/libraries/Decimal'
 import GraphQLClient from '@/libraries/GraphQLClient'
 import {
   generateBundleHash,
-  generateSecret
+  generateSecret,
+  generateBatchId
 } from '@/libraries/crypto'
 import Molecule from '@/core/Molecule'
 import Wallet from '@/core/Wallet'
@@ -80,7 +81,6 @@ import QueryBatchHistory from '@/query/QueryBatchHistory'
 import QueryAtom from '@/query/QueryAtom'
 import QueryPolicy from '@/query/QueryPolicy'
 import QueryActiveSession from '@/query/QueryActiveSession'
-import QueryUserActivity from '@/query/QueryUserActivity'
 import QueryToken from '@/query/QueryToken'
 import QueryMetaTypeViaAtom from '@/query/QueryMetaTypeViaAtom'
 import QueryMetaTypeViaMolecule from '@/query/QueryMetaTypeViaMolecule'
@@ -121,6 +121,7 @@ import {
   TransferBalanceException,
   WalletShadowException,
   StackableUnitAmountException,
+  StackableUnitDecimalsException,
   AuthorizationRejectedException,
   MolecularHashMismatchException,
   SignatureMismatchException,
@@ -137,7 +138,8 @@ import type {
   MetaId,
   BatchId,
   MetaFilter,
-  RequestPolicy
+  RequestPolicy,
+  TransferRecipientInput
 } from '@/types'
 
 /**
@@ -801,6 +803,96 @@ export default class KnishIOClient {
     return await this.executeQuery(query)
   }
 
+  /**
+   * Fund N recipients from a single source in ONE molecule (multi-recipient sibling of
+   * transferToken). Each recipient gets its own subset of stackable units (or a fungible
+   * amount); a remainder returns the rest to the sender. Conserves:
+   * -balance + Σamounts + (balance - Σ) === 0.
+   *
+   * @param token - token slug
+   * @param recipients - destinations (bundleHash + units OR amount + optional batchId)
+   * @param sourceWallet - optional pre-resolved source (defaults to the client's own wallet)
+   */
+  async transferTokens({
+    token,
+    recipients,
+    sourceWallet = null
+  }: {
+    token: string
+    recipients: TransferRecipientInput[]
+    sourceWallet?: Wallet | null
+  }): Promise<Response | null> {
+    // Per-recipient amount: stackable -> unit count; fungible -> explicit amount (never both)
+    const amounts: number[] = recipients.map(recipient => {
+      const unitCount = recipient.units ? recipient.units.length : 0
+      if (unitCount > 0) {
+        if (recipient.amount !== null && recipient.amount !== undefined && recipient.amount > 0) {
+          throw new StackableUnitAmountException()
+        }
+        return unitCount
+      }
+      return recipient.amount ?? 0
+    })
+
+    const total = amounts.reduce((sum, amount) => sum + amount, 0)
+
+    // Resolve the source (queryBalance now carries tokenUnits, so the split below sees real units)
+    if (sourceWallet === null) {
+      sourceWallet = await this.querySourceWallet({
+        token,
+        amount: total
+      })
+    }
+
+    if (sourceWallet === null || Decimal.cmp(Number(sourceWallet.balance), total) < 0) {
+      throw new TransferBalanceException()
+    }
+
+    // Build a shadow recipient wallet per destination + assign a distinct batch id
+    const recipientWallets: Wallet[] = recipients.map(recipient => {
+      const recipientWallet = Wallet.create({
+        bundle: recipient.bundleHash,
+        token
+      })
+      if (recipient.batchId !== null && recipient.batchId !== undefined) {
+        recipientWallet.batchId = recipient.batchId
+      } else {
+        recipientWallet.initBatchId({ sourceWallet: sourceWallet as Wallet })
+      }
+      return recipientWallet
+    })
+
+    // Canonical remainder (carries the source's token/characters; reuses the source batch id)
+    const remainderWallet = sourceWallet.createRemainder(this.getSecret())
+
+    // Stackable (NFT): partition the source's tokenUnits across source (SENT union), each
+    // recipient (its subset), and remainder (KEPT) BEFORE the molecule is built. No-op for fungible.
+    if (recipients.some(recipient => recipient.units && recipient.units.length > 0)) {
+      sourceWallet.splitUnitsMulti(
+        recipients.map(recipient => recipient.units ?? []),
+        recipientWallets,
+        remainderWallet
+      )
+    }
+
+    const molecule = await this.createMolecule({
+      sourceWallet,
+      remainderWallet
+    })
+
+    const query = await this.createMoleculeMutation({
+      mutationClass: MutationTransferTokens,
+      molecule
+    })
+
+    query.fillMoleculeMulti({
+      recipientWallets,
+      amounts
+    })
+
+    return await this.executeQuery(query)
+  }
+
   /**
    * Request authorization token (guest or profile)
    *
@@ -1436,51 +1528,6 @@ export default class KnishIOClient {
     }) as Promise<Response>
   }
 
-  /**
-   * Query user activity
-   */
-  async queryUserActivity({
-    bundleHash,
-    metaType,
-    metaId,
-    ipAddress = null,
-    browser = null,
-    osCpu = null,
-    resolution = null,
-    timeZone = null,
-    countBy = null,
-    interval = null
-  }: {
-    bundleHash: BundleHash | string
-    metaType: MetaType | string
-    metaId: MetaId | string
-    ipAddress?: string | null
-    browser?: string | null
-    osCpu?: string | null
-    resolution?: string | null
-    timeZone?: string | null
-    countBy?: string | null
-    interval?: string | null
-  }): Promise<Response> {
-    const query = this.createQuery(QueryUserActivity)
-
-    const variables: Record<string, any> = {
-      bundleHash,
-      metaType,
-      metaId
-    }
-
-    if (ipAddress !== null) variables.ipAddress = ipAddress
-    if (browser !== null) variables.browser = browser
-    if (osCpu !== null) variables.osCpu = osCpu
-    if (resolution !== null) variables.resolution = resolution
-    if (timeZone !== null) variables.timeZone = timeZone
-    if (countBy !== null) variables.countBy = countBy
-    if (interval !== null) variables.interval = interval
-
-    return this.executeQuery(query, variables) as Promise<Response>
-  }
-
   /**
    * Query token information
    */
@@ -1620,7 +1667,7 @@ export default class KnishIOClient {
     amount = null,
     meta = null,
     batchId = null,
-    units: _units = null
+    units = null
   }: {
     token: TokenSlug | string
     amount?: number | string | null
@@ -1630,6 +1677,33 @@ export default class KnishIOClient {
   }): Promise<Response> {
     this.log('info', `KnishIOClient::createToken() - Creating token ${token}...`)
 
+    const tokenMeta: Record<string, any> = meta || {}
+    const fungibility = tokenMeta.fungibility
+    let resolvedAmount: number | string = amount ?? 0
+
+    // For a stackable token, ensure a batch ID is present (mirror JS createToken)
+    if (fungibility === 'stackable') {
+      tokenMeta.batchId = batchId || generateBatchId({})
+    }
+
+    // Token-unit initialization for stackable / nonfungible tokens: the unit IDs ARE the supply.
+    // Meta values are sent as strings (the validator's MetaItemInput.value is a GraphQL String).
+    if (
+      (fungibility === 'stackable' || fungibility === 'nonfungible' || fungibility === 'non-fungible') &&
+      units && units.length > 0
+    ) {
+      if (Number(tokenMeta.decimals ?? 0) > 0) {
+        throw new StackableUnitDecimalsException()
+      }
+      if (Number(amount ?? 0) > 0) {
+        throw new StackableUnitAmountException()
+      }
+      resolvedAmount = units.length
+      tokenMeta.splittable = '1'
+      tokenMeta.decimals = '0'
+      tokenMeta.tokenUnits = JSON.stringify(units)
+    }
+
     // Create the molecule mutation
     const mutation = await this.createMoleculeMutation({ mutationClass: MutationCreateToken })
 
@@ -1644,8 +1718,8 @@ export default class KnishIOClient {
     // Initialize the create token mutation
     await mutation.fillMolecule({
       recipientWallet,
-      amount: amount ?? 0,
-      meta
+      amount: resolvedAmount,
+      meta: tokenMeta
     })
 
     // Execute the mutation
@@ -2333,9 +2407,17 @@ export default class KnishIOClient {
       molecule
     })
 
-    // Initialize the profile auth mutation
+    // Initialize the profile auth mutation.
+    // PQ-transport Phase E: convey the AUTH source wallet's ML-KEM768 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.
+    const authMeta: Record<string, string> = { encrypt: encrypt ? 'true' : 'false' }
+    if (wallet.pubkey) {
+      authMeta.walletPubkey = wallet.pubkey
+    }
     mutation.fillMolecule({
-      meta: { encrypt: encrypt ? 'true' : 'false' }
+      meta: authMeta
     })
 
     // Execute the mutation

package/src/constants.ts

@@ -231,8 +231,7 @@ export const QUERY_TYPES = [
   'Batch',
   'ActiveSession',
   'Policy',
-  'Token',
-  'UserActivity'
+  'Token'
 ] as const
 
 export type QueryType = typeof QUERY_TYPES[number]

package/src/core/Molecule.ts

@@ -319,6 +319,59 @@ export default class Molecule {
     return this
   }
 
+  /**
+   * Initialize a MULTI-recipient V-type molecule: one source debits its FULL balance to fund
+   * N recipients (each its own amount + stackable units) plus a remainder back to the sender.
+   * Multi-recipient sibling of initValue (WP line 544: fund multiple recipients with one
+   * transaction). recipientWallets is parallel to amounts.
+   */
+  initValues({
+    recipientWallets,
+    amounts
+  }: {
+    recipientWallets: Wallet[]
+    amounts: number[]
+  }): Molecule {
+    if (!this.sourceWallet) {
+      throw new Error('Source wallet required for value transfer')
+    }
+
+    const total = amounts.reduce((sum, amount) => sum + amount, 0)
+
+    if (Number(this.sourceWallet.balance) - total < 0) {
+      throw new BalanceInsufficientException()
+    }
+
+    // Source atom: debit the ENTIRE balance (UTXO drain); carries the SENT union of token units
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.sourceWallet,
+      value: -Number(this.sourceWallet.balance)
+    }))
+
+    // One atom per recipient: +amount_i, walletBundle -> recipient bundle, its own SENT units
+    recipientWallets.forEach((recipientWallet, i) => {
+      this.addAtom(Atom.create({
+        isotope: 'V',
+        wallet: recipientWallet,
+        value: amounts[i]!,
+        metaType: 'walletBundle',
+        metaId: recipientWallet.bundle!
+      }))
+    })
+
+    // Remainder atom: +(balance - total), walletBundle -> sender bundle, KEPT units
+    this.addAtom(Atom.create({
+      isotope: 'V',
+      wallet: this.remainderWallet!,
+      value: Number(this.sourceWallet.balance) - total,
+      metaType: 'walletBundle',
+      metaId: this.remainderWallet!.bundle!
+    }))
+
+    return this
+  }
+
   /**
    * Sign the molecule with one-time signature
    * Matches JavaScript SDK sign method

package/src/core/Wallet.ts

@@ -349,6 +349,42 @@ export default class Wallet {
     remainderWallet.tokenUnits = remainderTokenUnits
   }
 
+  /**
+   * Split token units across MULTIPLE recipients (N-way sibling of splitUnits).
+   *
+   * The source retains the SENT union (all units leaving), each recipient gets its own
+   * subset, and the remainder keeps the KEPT units (those not assigned to any recipient).
+   * recipientUnitLists is parallel to recipientWallets. No-op when no units are sent.
+   *
+   * @param recipientUnitLists - per-recipient arrays of token unit IDs (parallel to recipientWallets)
+   * @param recipientWallets - destination wallets
+   * @param remainderWallet - wallet to receive the KEPT units
+   */
+  splitUnitsMulti(
+    recipientUnitLists: string[][],
+    recipientWallets: Wallet[],
+    remainderWallet: Wallet
+  ): void {
+    const sentIds = new Set<string>(recipientUnitLists.flat())
+
+    // Nothing to split (fungible transfer) — leave token units untouched
+    if (sentIds.size === 0) {
+      return
+    }
+
+    // Each recipient gets its own subset of the source's token units
+    recipientWallets.forEach((recipientWallet, i) => {
+      const ids = recipientUnitLists[i] ?? []
+      recipientWallet.tokenUnits = this.tokenUnits.filter(tokenUnit => ids.includes(tokenUnit.id))
+    })
+
+    // The remainder keeps everything not sent to any recipient (KEPT)
+    remainderWallet.tokenUnits = this.tokenUnits.filter(tokenUnit => !sentIds.has(tokenUnit.id))
+
+    // The source carries the SENT union (the ownership authority the validator reads)
+    this.tokenUnits = this.tokenUnits.filter(tokenUnit => sentIds.has(tokenUnit.id))
+  }
+
   /**
    * Get token units data
    * Stub for compatibility
@@ -401,6 +437,18 @@ 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) {
+      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 }.`
+      )
+    }
     const { cipherText, sharedSecret } = ml_kem768.encapsulate(deserializedPubkey)
     const encryptedMessage = await this.encryptWithSharedSecret(messageUint8, sharedSecret)
     return {
@@ -410,6 +458,16 @@ export default class Wallet {
   }
 
   async decryptMessage(encryptedData: { cipherText: string; encryptedMessage: string }): Promise<any> {
+    const decryptedString = await this._mlkemDecryptToString(encryptedData)
+    return decryptedString === null ? null : JSON.parse(decryptedString)
+  }
+
+  /**
+   * ML-KEM768 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.
+   */
+  async _mlkemDecryptToString(encryptedData: { cipherText: string; encryptedMessage: string }): Promise<string | null> {
     const { cipherText, encryptedMessage } = encryptedData
     let sharedSecret
     try {
@@ -438,9 +496,8 @@ export default class Wallet {
       console.info('Wallet::decryptMessage() - deserialized encrypted message', deserializedEncryptedMessage)
       return null
     }
-    let decryptedString
     try {
-      decryptedString = new TextDecoder().decode(decryptedUint8)
+      return new TextDecoder().decode(decryptedUint8)
     } catch (e) {
       console.warn('Wallet::decryptMessage() - Decoding failed', e)
       console.info('Wallet::decryptMessage() - my public key', this.pubkey)
@@ -449,7 +506,43 @@ export default class Wallet {
       console.info('Wallet::decryptMessage() - decrypted Uint8Array', decryptedUint8)
       return null
     }
-    return JSON.parse(decryptedString)
+  }
+
+  /**
+   * Canonical cross-SDK hashShare for a public key: standard base64 of SHAKE256(pubkey_utf8, 8 bytes)
+   * — byte-matches the validator's hash_share and the JS/Kotlin/PHP hashShare. `shake256(pubkey, 64)`
+   * = 64 bits = 8 bytes (hex) → hex-decode → standard base64 via serializeKey. PQ-transport Phase E.
+   */
+  hashShare(pubkey: string): string {
+    const hex = shake256(pubkey, 64)
+    const bytes = new Uint8Array(hex.length / 2)
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = parseInt(hex.substr(i * 2, 2), 16)
+    }
+    return this.serializeKey(bytes)
+  }
+
+  /**
+   * Post-quantum (ML-KEM768) 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> {
+    const envelope = await this.encryptMessage(message, recipientPubkey)
+    return JSON.stringify({ [this.hashShare(recipientPubkey)]: envelope })
+  }
+
+  /**
+   * 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.
+   */
+  async decryptMyMessageML768(map: Record<string, { cipherText: string; encryptedMessage: string }>): Promise<string | null> {
+    const envelope = map[this.hashShare(this.pubkey)]
+    if (!envelope) {
+      return null
+    }
+    return this._mlkemDecryptToString(envelope)
   }
 
   // =============================================================================

package/src/libraries/Decimal.ts

@@ -72,7 +72,7 @@ export default class Decimal {
    * @param debug Enable debug logging
    * @returns 0 if equal, 1 if value1 > value2, -1 if value1 < value2
    */
-  static cmp(value1: number, value2: number, debug: boolean = false): number {
+  static cmp(value1: number, value2: number, _debug: boolean = false): number {
     const val1 = Decimal.val(value1) * MULTIPLIER
     const val2 = Decimal.val(value2) * MULTIPLIER
 

package/src/libraries/GraphQLClient.ts

@@ -62,6 +62,22 @@ import type {
 } from '@/types'
 import type Wallet from '@/core/Wallet'
 
+const CIPHER_HASH_QUERY = 'query ( $Hash: String! ) { CipherHash ( Hash: $Hash ) { hash } }'
+
+/**
+ * Light parse of a GraphQL request body's operation type + root field name, for the CipherHash
+ * bypass decision (no full GraphQL parse needed). Operation type = the first query/mutation/
+ * subscription keyword (default 'query' for an anonymous `{ ... }`); root field = the first
+ * identifier inside the top-level selection set.
+ */
+function parseOperation(query: string): { type: string; name: string } {
+  const typeMatch = (query || '').match(/\b(query|mutation|subscription)\b/i)
+  const type = typeMatch?.[1]?.toLowerCase() ?? 'query'
+  const braceIdx = (query || '').indexOf('{')
+  const nameMatch = braceIdx >= 0 ? query.slice(braceIdx + 1).match(/[A-Za-z_][A-Za-z0-9_]*/) : null
+  return { type, name: nameMatch?.[0] ?? '' }
+}
+
 /**
  * GraphQL client wrapper for KnishIO SDK
  * Provides a unified interface for GraphQL operations
@@ -125,6 +141,10 @@ 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 } : {}),
       fetchOptions: () => ({
         headers: {
           'X-Auth-Token': this.$__authToken
@@ -135,6 +155,69 @@ export default class GraphQLClient implements IGraphQLClient {
     })
   }
 
+  /**
+   * Whether an outgoing GraphQL request body should be wrapped in CipherHash. Bypass (plaintext):
+   * introspection `__schema`, `ContinuId`, the `AccessToken` mutation, and the U-isotope
+   * `ProposeMolecule` (auth bootstrap — the key exchange itself can't be encrypted). Mirrors the
+   * Kotlin/PHP/validator bypass set.
+   */
+  private shouldEncrypt(body: string): boolean {
+    let parsed: any
+    try {
+      parsed = JSON.parse(body)
+    } catch (e) {
+      return false
+    }
+    const { type, name } = parseOperation(parsed.query)
+    if (type === 'query' && (name === '__schema' || name === 'ContinuId')) return false
+    if (type === 'mutation' && name === 'AccessToken') return false
+    if (type === 'mutation' && name === 'ProposeMolecule') {
+      const isotope = parsed.variables?.molecule?.atoms?.[0]?.isotope
+      if (isotope === 'U') return false
+    }
+    return true
+  }
+
+  /**
+   * Custom `fetch` that wraps a GraphQL request in the ML-KEM CipherHash envelope and decrypts the
+   * response (PQ-transport Phase E). Operates on the raw POST body (mirrors the JS/Kotlin transform).
+   * Reads the CURRENT client wallet + validator pubkey from auth.
+   */
+  private async cipherFetch(input: any, init: any): Promise<Response> {
+    const wallet = this.$__wallet
+    const serverPubkey = this.$__pubkey
+    let encryptedRequest = false
+    let requestInit = init
+
+    if (wallet && serverPubkey && init && typeof init.body === 'string' && this.shouldEncrypt(init.body)) {
+      const hashVar = await wallet.encryptStringML768(init.body, serverPubkey)
+      requestInit = { ...init, body: JSON.stringify({ query: CIPHER_HASH_QUERY, variables: { Hash: hashVar } }) }
+      encryptedRequest = true
+    }
+
+    const response = await fetch(input, requestInit)
+    if (!encryptedRequest) {
+      return response
+    }
+
+    // Decrypt the CipherHash response back to the inner GraphQL response JSON.
+    const text = await response.text()
+    const init2 = { status: response.status, statusText: response.statusText, headers: response.headers }
+    let parsed: any
+    try {
+      parsed = JSON.parse(text)
+    } catch (e) {
+      return new Response(text, init2)
+    }
+    const hash = parsed?.data?.CipherHash?.hash
+    if (typeof hash !== 'string') {
+      // Plaintext (e.g. a validator-side error response) — pass through unchanged.
+      return new Response(text, init2)
+    }
+    const decrypted = await wallet!.decryptMyMessageML768(JSON.parse(hash))
+    return new Response(decrypted != null ? decrypted : text, init2)
+  }
+
   setAuthData({
     token,
     pubkey,

package/src/libraries/Hex.ts

@@ -72,7 +72,8 @@ export default class Hex {
         ? ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F']
         : ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f']
 
-      return set[Math.floor(val / 16)] + set[val % 16]
+      // indices are provably in-range (val is a byte; /16 and %16 are 0..15 for a 16-elem set)
+      return set[Math.floor(val / 16)]! + set[val % 16]!
     }
 
     const opts: Required<HexOptions> = Object.assign(
@@ -97,7 +98,7 @@ export default class Hex {
     let column = 0
 
     for (let i = 0; i < arrayLike.length; ++i) {
-      str += numberToHex(arrayLike[i], opts.uppercase)
+      str += numberToHex(arrayLike[i]!, opts.uppercase)
 
       if (i === arrayLike.length - 1) {
         break
@@ -135,7 +136,7 @@ export default class Hex {
     let curr = -1
 
     for (let i = 0; i < target.length; ++i) {
-      const c = target[i]
+      const c = target[i]!
       const val = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'].indexOf(c)
 
       if (val === -1) {