@wishknish/knishio-client-ts 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "1.2.0",
+  "version": "1.3.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",
@@ -81,7 +81,11 @@
     "vitest": "^4.1.11"
   },
   "resolutions": {
-    "wonka": "6.3.6"
+    "wonka": "6.3.6",
+    "esbuild": "^0.28.1"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
   },
   "browserslist": [
     "> 1%",

package/src/AuthToken.ts

@@ -53,7 +53,9 @@ import Wallet from '@/core/Wallet'
  * 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}.
+ * the default do not carry it — see {@link AuthToken.resolveMlKemParameterSet}. `wallet.token` is
+ * optional because snapshots persisted before re-logins were signed from the USER ContinuID
+ * wallet do not carry it; every such session was signed from an AUTH wallet.
  */
 export type AuthTokenSnapshot = {
   token: string
@@ -61,6 +63,7 @@ export type AuthTokenSnapshot = {
   pubkey: string
   encrypt: boolean
   wallet?: {
+    token?: string
     position: string | null
     characters: string | null
     mlKemParameterSet?: 1024 | 768
@@ -134,7 +137,7 @@ export default class AuthToken {
   static restore(snapshot: AuthTokenSnapshot, secret: string): AuthToken {
     const wallet = new Wallet({
       secret,
-      token: 'AUTH',
+      token: snapshot.wallet?.token ?? 'AUTH',
       position: snapshot.wallet?.position ?? null,
       characters: snapshot.wallet?.characters ?? null,
       mlKemParameterSet: AuthToken.resolveMlKemParameterSet(snapshot)
@@ -232,6 +235,7 @@ export default class AuthToken {
       encrypt: this.$__encrypt,
       ...(this.$__wallet ? {
         wallet: {
+          token: this.$__wallet.token,
           position: this.$__wallet.position,
           characters: this.$__wallet.characters,
           mlKemParameterSet: this.$__wallet.mlKemParameterSet

package/src/KnishIOClient.ts

@@ -1014,38 +1014,41 @@ export default class KnishIOClient {
       this.setCellSlug(cellSlug)
     }
 
-    // Auth in process...
+    // Auth in process... Cleared in `finally`: a rejected login must not leave the guard set, or
+    // executeQuery never refreshes an expired token again.
     this.$__authInProcess = true
 
-    // Auth token response
-    let response: Response
-
-    // Authorized user (profile auth with secret)
-    if (secret) {
-      response = await this.requestProfileAuthToken({
-        secret,
-        encrypt
-      })
-    } else {
-      // Guest auth (no secret)
-      response = await this.requestGuestAuthToken({
-        cellSlug: cellSlug || this.getCellSlug(),
-        encrypt
-      })
-    }
-
-    // Log success
-    if (this.$__authToken) {
-      this.log('info', `KnishIOClient::requestAuthToken() - Successfully retrieved auth token...`)
-    }
+    try {
+      // Auth token response
+      let response: Response
+
+      // Authorized user (profile auth with secret)
+      if (secret) {
+        response = await this.requestProfileAuthToken({
+          secret,
+          encrypt
+        })
+      } else {
+        // Guest auth (no secret)
+        response = await this.requestGuestAuthToken({
+          cellSlug: cellSlug || this.getCellSlug(),
+          encrypt
+        })
+      }
 
-    // Handle encryption if needed
-    this.switchEncryption(encrypt)
+      // Log success
+      if (this.$__authToken) {
+        this.log('info', `KnishIOClient::requestAuthToken() - Successfully retrieved auth token...`)
+      }
 
-    // Auth process is stopped
-    this.$__authInProcess = false
+      // Handle encryption if needed
+      this.switchEncryption(encrypt)
 
-    return response
+      return response
+    } finally {
+      // Auth process is stopped
+      this.$__authInProcess = false
+    }
   }
 
   /**
@@ -1233,17 +1236,20 @@ export default class KnishIOClient {
 
   /**
    * Query next ContinuId wallet
+   *
+   * @param token - Restricts the lookup to wallets of this token. Without it the validator falls
+   *   back to the bundle's newest wallet of ANY token when the bundle has no ContinuID pointer.
    */
   async queryContinuId({
-    bundle
+    bundle,
+    token = null
   }: {
     bundle: BundleHash | string
+    token?: string | null
   }): Promise<Response> {
     const query = this.createQuery(QueryContinuId)
 
-    return this.executeQuery(query, {
-      bundle
-    }) as Promise<Response>
+    return this.executeQuery(query, token ? { bundle, token } : { bundle }) as Promise<Response>
   }
 
   /**
@@ -2433,13 +2439,11 @@ export default class KnishIOClient {
   async withdrawBufferToken({
     tokenSlug,
     amount,
-    sourceWallet = null,
-    signingWallet = null
+    sourceWallet = null
   }: {
     tokenSlug: TokenSlug | string
     amount: number | string
     sourceWallet?: Wallet | null
-    signingWallet?: Wallet | null
   }): Promise<Response> {
     this.log('info', `KnishIOClient::withdrawBufferToken() - Withdrawing ${amount} of ${tokenSlug} from buffer...`)
 
@@ -2454,12 +2458,7 @@ export default class KnishIOClient {
     // Initialize the withdraw buffer token mutation
     const recipients: Record<string, any> = {}
     recipients[this.getBundle()] = amount
-    // Only include signingWallet if it exists (exactOptionalPropertyTypes compliance)
-    const fillMoleculeParams: any = { recipients }
-    if (signingWallet) {
-      fillMoleculeParams.signingWallet = signingWallet
-    }
-    await mutation.fillMolecule(fillMoleculeParams)
+    await mutation.fillMolecule({ recipients })
 
     // Execute the mutation
     const response = await this.executeQuery(mutation)
@@ -2487,29 +2486,43 @@ export default class KnishIOClient {
   } = {}): Promise<Response> {
     this.log('info', 'KnishIOClient::requestGuestAuthToken() - Requesting guest auth token...')
 
-    // Create the mutation (extends Mutation directly, not MutationProposeMolecule)
-    const mutation = this.createQuery(MutationRequestAuthorizationGuest)
+    // Hold the auth guard so this login's own request does not start a nested token refresh.
+    // Restore the caller's value: requestAuthToken holds it until its own `finally`.
+    const authInProcess = this.$__authInProcess
+    this.$__authInProcess = true
+    try {
+      // Create the mutation (extends Mutation directly, not MutationProposeMolecule)
+      const mutation = this.createQuery(MutationRequestAuthorizationGuest)
 
-    // Execute with variables
-    const response = await this.executeQuery(mutation, {
-      cellSlug: cellSlug || this.getCellSlug()
-    })
+      // Execute with variables
+      const response = await this.executeQuery(mutation, {
+        cellSlug: cellSlug || this.getCellSlug()
+      })
 
-    if (!response) {
-      throw new CodeException('Guest auth token request failed')
-    }
+      if (!response) {
+        throw new CodeException('Guest auth token request failed')
+      }
 
-    // Handle encryption if needed
-    if (encrypt) {
-      this.switchEncryption(true)
-    }
+      // Handle encryption if needed
+      if (encrypt) {
+        this.switchEncryption(true)
+      }
 
-    return response
+      return response
+    } finally {
+      this.$__authInProcess = authInProcess
+    }
   }
 
   /**
    * Request profile authentication token
-   * Matches JavaScript SDK requestProfileAuthToken implementation
+   *
+   * A returning user (the bundle has a USER ContinuID pointer) signs from the USER wallet
+   * registered at that pointer, so validator 0.5.0+ marks the token proven and the identity keeps
+   * read/subscription access to permissioned and private cells. A first login — or a pointer this
+   * secret does not own — signs from a fresh AUTH wallet as before. A rejected pointer-signed
+   * login falls back to the AUTH login exactly once, so one call sends at most two
+   * authorization molecules (testnet allows 3 auths/min/IP).
    */
   async requestProfileAuthToken({
     secret,
@@ -2523,16 +2536,70 @@ export default class KnishIOClient {
     // Set the secret
     this.setSecret(secret)
 
-    // Generate a signing wallet with AUTH token (matching JavaScript SDK)
-    const wallet = new Wallet({
-      secret,
-      token: 'AUTH',
-      mlKemParameterSet: this.getMlKemParameterSet()
-    })
+    // Hold the auth guard so this login's own requests do not start a nested token refresh (a
+    // second login that would sign at the same pointer). Restore the caller's value:
+    // requestAuthToken holds it until its own `finally`.
+    const authInProcess = this.$__authInProcess
+    this.$__authInProcess = true
+    try {
+      // Filtered to USER: unfiltered, a bundle without a pointer answers with its newest wallet of
+      // any token, which is not an identity wallet the validator would accept as the signer.
+      const pointer = (await this.queryContinuId({
+        bundle: this.getBundle(),
+        token: 'USER'
+      }))?.payload() as Wallet | null
+
+      let pointerWallet: Wallet | null = null
+      if (pointer && pointer.token === 'USER' && pointer.position) {
+        const wallet = new Wallet({
+          secret,
+          token: 'USER',
+          position: pointer.position,
+          mlKemParameterSet: this.getMlKemParameterSet()
+        })
+        if (!pointer.address || wallet.address === pointer.address) {
+          pointerWallet = wallet
+        } else {
+          this.log('warn', 'KnishIOClient::requestProfileAuthToken() - ContinuID wallet address does not derive from this secret; signing from a fresh AUTH wallet')
+        }
+      }
+
+      if (pointerWallet) {
+        const response = await this.proposeProfileAuthorization(pointerWallet, encrypt)
+        if (response.success()) {
+          this.log('info', 'KnishIOClient::requestProfileAuthToken() - Auth token signed from the ContinuID pointer (proven)')
+          return this.acceptProfileAuthorization(response, pointerWallet, encrypt)
+        }
+        this.log('warn', `KnishIOClient::requestProfileAuthToken() - Pointer-signed authorization rejected (${response.reason()}); falling back once to an AUTH-wallet login`)
+      }
+
+      // Generate a signing wallet with AUTH token (matching JavaScript SDK)
+      const wallet = new Wallet({
+        secret,
+        token: 'AUTH',
+        mlKemParameterSet: this.getMlKemParameterSet()
+      })
+      const response = await this.proposeProfileAuthorization(wallet, encrypt)
 
-    // Create a molecule with the AUTH wallet as source
+      if (!response.success()) {
+        throw new AuthorizationRejectedException(
+          `KnishIOClient::requestProfileAuthToken() - Authorization attempt rejected by ledger. Reason: ${response.reason()}`
+        )
+      }
+
+      this.log('info', `KnishIOClient::requestProfileAuthToken() - Auth token signed from a fresh AUTH wallet (${pointerWallet ? 'fallback after the pointer-signed login was rejected' : 'no usable ContinuID pointer'})`)
+      return this.acceptProfileAuthorization(response, wallet, encrypt)
+    } finally {
+      this.$__authInProcess = authInProcess
+    }
+  }
+
+  /**
+   * Signs and proposes a profile authorization molecule from the given source wallet.
+   */
+  private async proposeProfileAuthorization(wallet: Wallet, encrypt: boolean): Promise<ResponseRequestAuthorization> {
     const molecule = await this.createMolecule({
-      secret,
+      secret: this.getSecret(),
       sourceWallet: wallet
     })
 
@@ -2543,7 +2610,7 @@ export default class KnishIOClient {
     })
 
     // Initialize the profile auth mutation.
-    // PQ-transport Phase E: convey the AUTH source wallet's ML-KEM public key as a SIGNED
+    // PQ-transport Phase E: convey the 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.
@@ -2562,21 +2629,26 @@ export default class KnishIOClient {
       throw new CodeException('Profile auth token request failed')
     }
 
-    // Did the authorization molecule get accepted?
-    if (response.success()) {
-      // Create & set an auth token from the response data
-      const authToken = AuthToken.create({
-        token: response.token(),
-        expiresAt: response.expiresAt(),
-        encrypt: String(response.encrypt()) === 'true',
-        pubkey: response.pubKey()
-      }, wallet)
-      this.setAuthToken(authToken)
-    } else {
-      throw new AuthorizationRejectedException(
-        `KnishIOClient::requestProfileAuthToken() - Authorization attempt rejected by ledger. Reason: ${response.reason()}`
-      )
-    }
+    return response
+  }
+
+  /**
+   * Binds the accepted authorization's token to the wallet that signed it.
+   */
+  private acceptProfileAuthorization(
+    response: ResponseRequestAuthorization,
+    wallet: Wallet,
+    encrypt: boolean
+  ): ResponseRequestAuthorization {
+    // Create & set an auth token from the response data
+    const authToken = AuthToken.create({
+      token: response.token(),
+      expiresAt: response.expiresAt(),
+      encrypt: String(response.encrypt()) === 'true',
+      pubkey: response.pubKey()
+    }, wallet)
+    this.setAuthToken(authToken)
+    this.lastMoleculeQuery = null
 
     // Handle encryption if needed
     if (encrypt) {

package/src/core/AtomMeta.ts

@@ -148,25 +148,6 @@ export default class AtomMeta {
     return this
   }
 
-  /**
-   * Set signing wallet metadata
-   * @param signingWallet - Wallet used for signing
-   * @return This instance for chaining
-   */
-  setSigningWallet(signingWallet: any): AtomMeta {
-    this.merge({
-      signingWallet: JSON.stringify({
-        tokenSlug: signingWallet.token,
-        bundleHash: signingWallet.bundle,
-        address: signingWallet.address,
-        position: signingWallet.position,
-        pubkey: signingWallet.pubkey,
-        characters: signingWallet.characters
-      })
-    })
-    return this
-  }
-
   /**
    * Add policy metadata
    * @param policy - Policy object to add

package/src/core/Molecule.ts

@@ -412,25 +412,8 @@ export default class Molecule {
       throw new SignatureMalformedException('No atoms available for signing!')
     }
 
-    // Set signing position from the first atom
-    let signingPosition = signingAtom.position
-
-    // Get signing wallet from first atom's metas (matching JS SDK exactly)
-    // This handles buffer withdraw reconciliation where a different wallet signs
-    const signingWalletMeta = signingAtom.aggregatedMeta ? signingAtom.aggregatedMeta() : null
-    const signingWalletJson = signingWalletMeta?.signingWallet as string | undefined
-    if (signingWalletJson) {
-      try {
-        const parsedSigningWallet = JSON.parse(signingWalletJson)
-        if (parsedSigningWallet.position) {
-          signingPosition = parsedSigningWallet.position
-        }
-      } catch {
-        // Invalid JSON in signingWallet meta, use default position
-      }
-    }
-
-    // Signing position is required
+    // The private key comes from the first atom's own position
+    const signingPosition = signingAtom.position
     if (!signingPosition) {
       throw new SignatureMalformedException('Signing wallet must have a position!')
     }
@@ -938,7 +921,7 @@ export default class Molecule {
     metaType: string
     metaId: string
     rule: Rule[] | any[] | any  // Accept single object or array
-    policy?: Record<string, any>
+    policy?: Record<string, any> | null
   }): Molecule {
     if (!this.sourceWallet) {
       throw new Error('Source wallet required for createRule')
@@ -958,10 +941,8 @@ export default class Molecule {
       rule: JSON.stringify(rules)
     })
 
-    // Add policies to meta object only if policy exists and has keys (matching JS SDK)
-    if (policy && Object.keys(policy).length > 0) {
-      atomMeta.addPolicy(policy)
-    }
+    // JS createRule always adds the policy (its {} default still fills per-key defaults).
+    atomMeta.addPolicy(policy ?? {})
 
     // Create R-isotope atom for rule (matching JS SDK)
     this.addAtom(Atom.create({
@@ -1294,15 +1275,12 @@ export default class Molecule {
    * Matches JavaScript SDK Molecule.initWithdrawBuffer implementation exactly
    *
    * @param recipients - Map of recipientBundle → amount
-   * @param signingWallet - Optional signing wallet for reconciliation
    * @return This molecule instance for chaining
    */
   initWithdrawBuffer({
-    recipients,
-    signingWallet = null
+    recipients
   }: {
     recipients: Record<string, number>
-    signingWallet?: any | null
   }): Molecule {
     if (!this.sourceWallet) {
       throw new Error('Source wallet required for buffer withdrawal')
@@ -1318,18 +1296,11 @@ export default class Molecule {
       throw new BalanceInsufficientException()
     }
 
-    // Set a meta signing position for molecule correct reconciliation
-    const firstAtomMeta = new AtomMeta()
-    if (signingWallet) {
-      firstAtomMeta.setSigningWallet(signingWallet)
-    }
-
     // Debit full balance from source (B-isotope)
     this.addAtom(Atom.create({
       isotope: 'B',
       wallet: this.sourceWallet,
       value: -Number(this.sourceWallet.balance),
-      meta: firstAtomMeta,
       metaType: 'walletBundle',
       metaId: this.sourceWallet.bundle!
     }))

package/src/index.ts

@@ -403,7 +403,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 = '1.2.0'
+export const SDK_VERSION = '1.3.0'
 export const SDK_NAME = 'KnishIO-Client-TS'
 export const COMPATIBLE_SERVER_VERSIONS = [4, 5]
 

package/src/libraries/CheckMolecule.ts

@@ -70,7 +70,6 @@ import Wallet from '@/core/Wallet'
 import Rule from '@/instance/rules/Rule'
 import { base64ToHex, chunkSubstr } from '@/libraries/strings'
 import { shake256 } from '@/libraries/crypto'
-import Dot from '@/libraries/Dot'
 import Molecule from '@/core/Molecule'
 
 // Type definitions for Molecule structure
@@ -214,12 +213,13 @@ export default class CheckMolecule {
   /**
    * Validate isotope U atoms
    * @return True if valid
-   * @throws WrongTokenTypeException if token is not AUTH
+   * @throws WrongTokenTypeException if token is neither AUTH (fresh login) nor USER (re-login
+   *   signed from the ContinuID pointer)
    * @throws AtomIndexException if index is not 0
    */
   isotopeU(): boolean {
     for (const atom of this.molecule.getIsotopes('U')) {
-      if (atom.token !== 'AUTH') {
+      if (atom.token !== 'AUTH' && atom.token !== 'USER') {
         throw new WrongTokenTypeException(`Check::isotopeU() - "${atom.token}" is not a valid Token slug for "${atom.isotope}" isotope Atoms!`)
       }
 
@@ -747,22 +747,8 @@ export default class CheckMolecule {
       throw new SignatureMismatchException()
     }
 
-    // Get a signing address
-    let signingAddress = signingAtom.walletAddress
-
-    // Get signing wallet from first atom's metas
-    const signingWallet = Dot.get(signingAtom.aggregatedMeta(), 'signingWallet')
-
-    // Try to get custom signing address from the metas (local molecule with server secret)
-    if (signingWallet) {
-      const parsedWallet = JSON.parse(signingWallet as string)
-      const walletAddress = Dot.get(parsedWallet, 'address')
-      if (walletAddress) {
-        signingAddress = walletAddress as string
-      }
-    }
-
-    if (address !== signingAddress) {
+    // The recovered address must match the address the signing atom claims
+    if (address !== signingAtom.walletAddress) {
       throw new SignatureMismatchException()
     }
 

package/src/mutation/MutationWithdrawBufferToken.ts

@@ -47,7 +47,6 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 */
 
 import MutationProposeMolecule from './MutationProposeMolecule'
-import type Wallet from '@/core/Wallet'
 
 /**
  * Mutation for withdrawing buffer tokens
@@ -57,15 +56,12 @@ export default class MutationWithdrawBufferToken extends MutationProposeMolecule
    * Fills the molecule with buffer withdrawal data
    */
   override fillMolecule({
-    recipients,
-    signingWallet
+    recipients
   }: {
     recipients: Record<string, any>
-    signingWallet?: Wallet
   }): void {
-    (this.$__molecule as any).initWithdrawBuffer({
-      recipients,
-      signingWallet
+    this.$__molecule.initWithdrawBuffer({
+      recipients
     })
     this.$__molecule.sign({})
     this.$__molecule.check(this.$__molecule.sourceWallet)

package/src/query/QueryContinuId.ts

@@ -64,8 +64,8 @@ export default class QueryContinuId extends Query {
   constructor(graphQLClient: GraphQLClient, knishIOClient: KnishIOClient) {
     super(graphQLClient, knishIOClient)
 
-    this.$__query = gql`query ($bundle: String!) {
-      ContinuId(bundle: $bundle) {
+    this.$__query = gql`query ($bundle: String!, $token: String) {
+      ContinuId(bundle: $bundle, token: $token) {
         address,
         bundleHash,
         tokenSlug,

package/src/response/ResponseProposeMolecule.ts

@@ -169,7 +169,8 @@ export default class ResponseProposeMolecule extends Response {
         code: 'HASH_MISMATCH'
       })
     }
-    if (/ots.*position.*reuse|position.*already.*used|ots.*verification/.test(lc)) {
+    // Validator 0.5.0 words the same rejection as "OTS key reuse rejected ... is already consumed".
+    if (/ots.*(?:position|key).*reuse|position.*already.*(?:used|consumed)|ots.*verification/.test(lc)) {
       return new SignatureMismatchException(reason, {
         details: { reason },
         code: 'OTS_VERIFICATION_FAILED'
@@ -187,6 +188,22 @@ export default class ResponseProposeMolecule extends Response {
         code: 'VERIFICATION_FAILED'
       })
     }
+    // Validator 0.5.0 signer binding (Tier 1): atom 0's address is not the wallet registered at
+    // (bundle, token, position). Nothing was consumed.
+    if (/signer address mismatch/.test(lc)) {
+      return new SignatureMismatchException(reason, {
+        details: { reason },
+        code: 'SIGNER_ADDRESS_MISMATCH'
+      })
+    }
+    // Validator 0.5.0 (Tier 2): the signing key is consumed and the chain advanced, so the
+    // cached remainder is stale — handlePositionDrift keys on AtomIndexException.
+    if (/no accepted origin available/.test(lc)) {
+      return new AtomIndexException(reason, {
+        details: { reason },
+        code: 'ORIGIN_PENDING'
+      })
+    }
     return null
   }