@tchain/tcabci-read-js-client 2.8.2 → 2.8.4

package/client.d.ts

@@ -21,6 +21,8 @@ export type {
   WebSocketConstructor
 } from './types.js'
 
+export type Randomizer = (data: Uint8Array) => Uint8Array
+
 export interface TxQuery {
   recipientAddrs?: readonly string[]
   senderAddrs?: readonly string[]
@@ -75,6 +77,7 @@ export default class TCaBCIClient {
 
   SetIsWeb(isWeb: boolean): this
   SetDebug(debug: boolean): this
+  SetRandomizer(randomizer: Randomizer): this
 
   SetSuccessCallback(cb: SuccessCallback | null): this
 

package/client.js

@@ -31,6 +31,7 @@ import { Options } from './websocketOptions.js'
 import { TWebSocket } from './websocket.js'
 import { Transaction, TX_TYPE_LIST } from './transaction.js'
 import { Block } from './block.js'
+import { passKey } from './passKey.js'
 import { HTTP } from './http.js'
 
 /**
@@ -66,6 +67,8 @@ export default class TCaBCIClient {
   _subscribed = false
   _subscribedAddresses = []
   _SubscribedSignedData = {}
+  _clientInstanceID = null
+  _instanceIDPromise = null
   _listenRequested = false
   _connected = false
   _chainName = 'transferchain'
@@ -98,6 +101,11 @@ export default class TCaBCIClient {
   _ws
   _readNodeAddress = READ_NODE_ADDRESS
   _readNodeWSAddress = READ_NODE_WS_ADDRESS
+  /**
+   * @type {(Uint8Array) => Uint8Array}
+   * @private
+   */
+  _randomizer = null
 
   /**
    * Create an HTTP/WebSocket client. Start initiates connection setup;
@@ -172,6 +180,15 @@ export default class TCaBCIClient {
     return this
   }
 
+  /**
+   * @param {(Uint8Array) => Uint8Array} randomizer
+   * @return {TCaBCIClient}
+   */
+  SetRandomizer(randomizer) {
+    this._randomizer = randomizer
+    return this
+  }
+
   /**
    * @param {SuccessCallback} cb
    * @return {TCaBCIClient}
@@ -311,7 +328,11 @@ export default class TCaBCIClient {
     if (!this.IsConnected()) throw new Error(NOT_CONNECTED)
 
     this._ws.send(
-      new Message({ isWeb: this._isWeb, type: LISTENMessage }).ToJSON()
+      new Message({
+        isWeb: this._isWeb,
+        type: LISTENMessage,
+        clientInstanceID: this._clientInstanceID ?? undefined
+      }).ToJSON()
     )
     this._listenRequested = true
 
@@ -322,6 +343,7 @@ export default class TCaBCIClient {
    * Subscribe to at most 251 unique addresses, each at most 2048 characters.
    * The combined active address list is bounded. Proof maps are copied;
    * caller objects remain mutable. ACK updates IsSubscribed asynchronously.
+   * A random instance ID is retained by this client across reconnects.
    * @param {readonly string[]} addresses
    * @param {Readonly<Record<string, string>>} signedData
    * @param {readonly string[]|null} [txTypes=null]
@@ -329,7 +351,7 @@ export default class TCaBCIClient {
    */
   Subscribe(addresses, signedData, txTypes = null) {
     const requested = validateAddresses(addresses),
-      proof = validateSignedData(signedData)
+      suppliedProof = validateSignedData(signedData)
 
     if (
       txTypes !== null &&
@@ -342,13 +364,20 @@ export default class TCaBCIClient {
     if (!this.IsConnected()) throw new Error(NOT_CONNECTED)
 
     const addrs = validateAddresses([
-      ...new Set([...this._subscribedAddresses, ...requested])
-    ])
+        ...new Set([...this._subscribedAddresses, ...requested])
+      ]),
+      proof = Object.fromEntries(
+        addrs.map((address) => [
+          address,
+          suppliedProof[address] ?? this._SubscribedSignedData[address]
+        ])
+      )
 
     this._ws.send(
       new Message({
         isWeb: true,
         type: SUBSCRIBEMessage,
+        clientInstanceID: this._clientInstanceID,
         addrs: addrs,
         signedData: proof,
         txTypes
@@ -870,7 +899,13 @@ export default class TCaBCIClient {
       this._callCloseCallback(e)
     })
 
-    const start = ws.connect()
+    const start = (async () => {
+      await this._prepareInstanceID(this._randomizer)
+
+      if (!current()) return ws
+
+      return ws.connect()
+    })()
 
     this._startPromise = start
 
@@ -885,6 +920,27 @@ export default class TCaBCIClient {
     }
   }
 
+  _prepareInstanceID(randomizer = null) {
+    if (this._clientInstanceID !== null)
+      return Promise.resolve(this._clientInstanceID)
+
+    if (this._instanceIDPromise) return this._instanceIDPromise
+
+    const pending = passKey(randomizer)
+      .then((identity) => {
+        this._clientInstanceID ??= identity
+
+        return this._clientInstanceID
+      })
+      .finally(() => {
+        if (this._instanceIDPromise === pending) this._instanceIDPromise = null
+      })
+
+    this._instanceIDPromise = pending
+
+    return pending
+  }
+
   async _disconnect(code = 1000) {
     code = closeCode(code)
 
@@ -1030,7 +1086,7 @@ export default class TCaBCIClient {
           break
         case Subscription:
           if (_msg.State === OK) {
-            this._setSubscribed(true)
+            this._setSubscribed(this._subscribedAddresses.length > 0)
           } else {
             this._clearSubscription()
           }

package/constants.js

@@ -1,3 +1,3 @@
-export const CLIENT_VERSION = '2.8.2',
+export const CLIENT_VERSION = '2.8.3',
   READ_NODE_ADDRESS = 'https://read-node-01.transferchain.io',
   READ_NODE_WS_ADDRESS = 'wss://read-node-01.transferchain.io/ws'

package/message.d.ts

@@ -34,6 +34,7 @@ export default class Message {
     signedData?: Readonly<Record<string, string>> | null
     txTypes?: readonly TXType[] | null
     data?: JSONValue
+    clientInstanceID?: string
   })
 
   get IsWeb(): boolean | undefined

package/message.js

@@ -26,6 +26,7 @@ export default class Message {
   _txTypes
   _data
   _state
+  _clientInstanceID
 
   /**
    * @param {boolean} isWeb
@@ -34,6 +35,7 @@ export default class Message {
    * @param {?Object} signedData
    * @param {?Array<string>} txTypes
    * @param {*} data
+   * @param {string|undefined} clientInstanceID Optional 64- or 128-character lowercase hex instance ID.
    */
   constructor({
     isWeb,
@@ -41,10 +43,12 @@ export default class Message {
     addrs,
     signedData = null,
     txTypes = null,
-    data = null
+    data = null,
+    clientInstanceID
   } = {}) {
     this._is_web = isWeb
     this._type = type
+    this._clientInstanceID = clientInstanceID
 
     if (addrs && Array.isArray(addrs))
       this._addresses = Object.freeze(addresses(addrs))
@@ -128,6 +132,9 @@ export default class Message {
 
       if (typeof obj.state !== 'undefined') msg._state = obj.state
 
+      if (typeof obj.client_instance_id !== 'undefined')
+        msg._clientInstanceID = obj.client_instance_id
+
       msg._validate()
 
       return { message: Object.freeze(msg), error: null }
@@ -142,6 +149,9 @@ export default class Message {
     return JSON.stringify({
       is_web: this._is_web,
       type: this._type,
+      ...(typeof this._clientInstanceID !== 'undefined'
+        ? { client_instance_id: this._clientInstanceID }
+        : {}),
       ...(this._addresses ? { addresses: this._addresses } : {}),
       ...(this._signedAddresses
         ? { signed_addresses: this._signedAddresses }
@@ -153,6 +163,13 @@ export default class Message {
   }
 
   _validate() {
+    if (
+      typeof this._clientInstanceID !== 'undefined' &&
+      (typeof this._clientInstanceID !== 'string' ||
+        !/^(?:[0-9a-f]{64}|[0-9a-f]{128})$/.test(this._clientInstanceID))
+    )
+      throw new Error(INVALID_ARGUMENT_WITH_CS('client_instance_id'))
+
     if (
       typeof this._is_web !== 'undefined' &&
       typeof this._is_web !== 'boolean'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tchain/tcabci-read-js-client",
-  "version": "2.8.2",
+  "version": "2.8.4",
   "description": "TransferChain Fastest Read Network WebSocket Client",
   "homepage": "https://github.com/TransferChain/tcabci-read-js-client#readme",
   "bugs": {
@@ -21,6 +21,7 @@
     "client.js",
     "errors.js",
     "message.js",
+    "passKey.js",
     "transaction.js",
     "util.js",
     "websocket.js",

package/passKey.d.ts

@@ -0,0 +1,4 @@
+export declare type Randomizer = (data: Uint8Array) => Uint8Array
+
+/** Four UUID-v4 ASCII identifiers hashed with SHA-512; owned bytes are cleared. */
+export declare function passKey(randomizer?: Randomizer): Promise<string>

package/passKey.js

@@ -0,0 +1,48 @@
+/**
+ * SHA-512 of four concatenated lowercase UUID-v4 ASCII identifiers, matching
+ * SDK passKey defaults. Uses WebCrypto without a dependency on the SDK.
+ * Owned entropy, ASCII and digest bytes are cleared on success and failure.
+ * Immutable returned hex and runtime/native copies cannot be explicitly erased.
+ * @param {(Uint8Array) => Uint8Array} randomizer
+ * @returns {Promise<string>} 128 lowercase hex characters; not an auth credential.
+ */
+export async function passKey(randomizer = null) {
+  const entropy = new Uint8Array(64),
+    ascii = new Uint8Array(144)
+  let digest
+
+  try {
+    if (!randomizer) globalThis.crypto.getRandomValues(entropy)
+    else randomizer(entropy)
+
+    let offset = 0
+
+    for (let uuid = 0; uuid < 4; uuid++) {
+      const start = uuid * 16
+
+      entropy[start + 6] = (entropy[start + 6] & 15) | 64
+      entropy[start + 8] = (entropy[start + 8] & 63) | 128
+
+      for (let index = 0; index < 16; index++) {
+        if ([4, 6, 8, 10].includes(index)) ascii[offset++] = 45
+
+        const value = entropy[start + index]
+
+        for (const nibble of [value >>> 4, value & 15])
+          ascii[offset++] = nibble < 10 ? 48 + nibble : 87 + nibble
+      }
+    }
+
+    digest = new Uint8Array(
+      await globalThis.crypto.subtle.digest('SHA-512', ascii)
+    )
+
+    return Array.from(digest, (byte) =>
+      byte.toString(16).padStart(2, '0')
+    ).join('')
+  } finally {
+    entropy.fill(0)
+    ascii.fill(0)
+    digest?.fill(0)
+  }
+}

package/websocketOptions.js

@@ -342,7 +342,7 @@ export class Options {
         constructor(url, protocols) {
           const authority = options._authority
 
-          if (requiresAuthority && !authority
+          if (requiresAuthority && !authority)
             throw new Error('Websocket authority configuration released')
 
           super(url, protocols, {