@tchain/tcabci-read-js-client 2.8.0 → 2.8.1

package/authority.d.ts

@@ -0,0 +1,15 @@
+/** Caller-owned result; the input is valid only during the synchronous call. */
+export type WSAuthoritySigner = (payload: Uint8Array) => Uint8Array
+export type Randomizer = (data: Uint8Array) => Uint8Array
+
+export interface WSAuthorityOptions {
+  address: string
+  sign: WSAuthoritySigner
+}
+
+/** Fresh v3 header for one trusted WS handshake; never log or cache it. */
+export declare function createWSAuthorityV3(
+  address: string,
+  sign: WSAuthoritySigner,
+  randomizer?: Randomizer
+): string

package/authority.js

@@ -0,0 +1,63 @@
+import { SendThrow } from './util.js'
+
+/**
+ * Create a fresh read-node WS authority v3 header, valid for ten seconds and one
+ * handshake. Use only with trusted endpoints; never log or cache the result.
+ * The signer is synchronous, receives an owned Uint8Array valid during its
+ * call, and returns caller-owned signature bytes. No private key is retained.
+ * @param {string} address Configured TransferChain public address.
+ * @param {(payload: Uint8Array) => Uint8Array} sign Synchronous signer.
+ * @param {(Uint8Array) => Uint8Array} randomizer
+ * @returns {string}
+ */
+export function createWSAuthorityV3(address, sign, randomizer = null) {
+  if (
+    typeof address !== 'string' ||
+    address.length === 0 ||
+    address.length > 2048 ||
+    /[;\r\n]/.test(address) ||
+    typeof sign !== 'function'
+  )
+    throw new TypeError('Invalid websocket authority configuration')
+
+  const nonce = new Uint8Array(32),
+    hex = (bytes) =>
+      Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')
+  let payload, signature
+
+  try {
+    if (!randomizer) globalThis.crypto.getRandomValues(nonce)
+    else randomizer(nonce)
+
+    const timestamp = (BigInt(Date.now()) * 1000000n).toString(),
+      nonceHex = hex(nonce)
+
+    payload = new TextEncoder().encode(
+      `read-node/ws-authority/v3\n${address}\n${timestamp}\n${nonceHex}`
+    )
+
+    const result = sign(payload)
+
+    if (result && typeof result.then === 'function') {
+      Promise.resolve(result).catch(() => {})
+      SendThrow(new TypeError('Authority signer must be synchronous'))
+    }
+
+    if (
+      !(result instanceof Uint8Array) ||
+      result.length === 0 ||
+      result.length > 8192
+    )
+      SendThrow(new TypeError('Invalid websocket authority signature'))
+
+    signature = new Uint8Array(result)
+
+    return `${address};v3;${timestamp};${nonceHex};${hex(signature)}`
+  } catch {
+    throw new Error('Websocket authority creation failed')
+  } finally {
+    nonce.fill(0)
+    payload?.fill(0)
+    signature?.fill(0)
+  }
+}

package/client.d.ts

@@ -1,3 +1,5 @@
+export { createWSAuthorityV3 } from './authority.js'
+export type { WSAuthoritySigner, WSAuthorityOptions } from './authority.js'
 import { Transaction, TXType } from './transaction.js'
 import { TWebSocket } from './websocket.js'
 import {
@@ -71,6 +73,7 @@ export default class TCaBCIClient {
     options?: ClientOptions
   )
 
+  SetIsWeb(isWeb: boolean): this
   SetDebug(debug: boolean): this
 
   SetSuccessCallback(cb: SuccessCallback | null): this
@@ -109,6 +112,9 @@ export default class TCaBCIClient {
     txTypes?: readonly TXType[] | null
   ): this
 
+  /** Explicit Listen; requires a valid authority and repeats after reconnect. */
+  Listen(): this
+
   Unsubscribe(): this
 
   LastBlock(

package/client.js

@@ -1,3 +1,4 @@
+export { createWSAuthorityV3 } from './authority.js'
 import {
   addresses as validateAddresses,
   signedData as validateSignedData,
@@ -21,6 +22,8 @@ import Message, {
   Transaction as MTransaction,
   SUBSCRIBEMessage,
   UNSUBSCRIBEMessage,
+  LISTENMessage,
+  Listen as MListen,
   Subscription,
   OK
 } from './message.js'
@@ -63,6 +66,7 @@ export default class TCaBCIClient {
   _subscribed = false
   _subscribedAddresses = []
   _SubscribedSignedData = {}
+  _listenRequested = false
   _connected = false
   _chainName = 'transferchain'
   _chainVersion = 'v1'
@@ -135,11 +139,15 @@ export default class TCaBCIClient {
       ).href
     }
 
+    this._isWeb = true
     this._httpClient = new HTTP(this._readNodeAddress, options)
     this._options = new Options(this._readNodeWSAddress)
       .setAllowInsecure(options.allowInsecure)
       .setCustomWS(this._wsLibrary)
 
+    if (typeof options.authority !== 'undefined')
+      this._options.setAuthority(options.authority)
+
     if (typeof options.maxMessageBytes !== 'undefined')
       this._options.setMaxMessageBytes(options.maxMessageBytes)
 
@@ -154,6 +162,11 @@ export default class TCaBCIClient {
     if (chainVersion) this._chainVersion = chainVersion
   }
 
+  SetIsWeb(isWeb) {
+    this._isWeb = isWeb
+    return isWeb
+  }
+
   SetDebug(debug) {
     this._options.setDebug(debug)
 
@@ -268,6 +281,7 @@ export default class TCaBCIClient {
    * @returns {Promise<TCaBCIClient>}
    */
   async Stop(code = 1000) {
+    this._listenRequested = false
     this._httpClient.abort()
     await this._disconnect(code)
     this._setConnected(false)
@@ -289,6 +303,22 @@ export default class TCaBCIClient {
     })
   }
 
+  /**
+   * Explicitly request privileged Listen with a configured authority handshake.
+   * The request is repeated after reconnect. Rejection stops automatic retries.
+   * @returns {TCaBCIClient}
+   */
+  Listen() {
+    if (!this.IsConnected()) throw new Error(NOT_CONNECTED)
+
+    this._ws.send(
+      new Message({ isWeb: this._isWeb, type: LISTENMessage }).ToJSON()
+    )
+    this._listenRequested = true
+
+    return this
+  }
+
   /**
    * Subscribe to at most 251 unique addresses, each at most 2048 characters.
    * The combined active address list is bounded. Proof maps are copied;
@@ -325,6 +355,7 @@ export default class TCaBCIClient {
         txTypes
       }).ToJSON()
     )
+    this._listenRequested = false
     this._setSubscribeAddresses(addrs)._setSubscribeSignedData(proof)
 
     return this
@@ -334,7 +365,7 @@ export default class TCaBCIClient {
    * @return {TCaBCIClient}
    */
   Unsubscribe() {
-    if (!this.IsSubscribed()) {
+    if (!this.IsSubscribed() && !this._listenRequested) {
       throw new Error(NOT_SUBSCRIBED)
     }
 
@@ -347,6 +378,7 @@ export default class TCaBCIClient {
         }).ToJSON()
       )
     } finally {
+      this._listenRequested = false
       this._clearSubscription()
     }
 
@@ -820,6 +852,9 @@ export default class TCaBCIClient {
       if (!current()) return
 
       this._setConnected(true)
+
+      if (this._listenRequested) this.Listen()
+
       this._callSuccessCallback(e)
     })
     ws.addMessageListener((message) => {
@@ -878,6 +913,7 @@ export default class TCaBCIClient {
    */
   async Dispose() {
     await this.Stop()
+    this._options.setAuthority(null)
     this._successCb = null
     this._errorCb = null
     this._closeCb = null
@@ -981,6 +1017,17 @@ export default class TCaBCIClient {
 
           if (this._listenCb) this._listenCb(null, msg.transaction, null)
 
+          break
+        case MListen:
+          if (_msg.State !== OK) {
+            void this.Stop().catch(() => {})
+            this._callErrorCallback(new Error('Listen rejected'))
+
+            return
+          }
+
+          if (this._listenCb) this._listenCb(null, null, _msg)
+
           break
         case Subscription:
           if (_msg.State === OK) {

package/message.d.ts

@@ -1,7 +1,15 @@
 import { TXType } from './transaction.js'
 import { JSONValue, ParseResult } from './types.js'
 
-export type MessageType = 'subscribe' | 'unsubscribe' | 0 | 1 | 2 | 3 | 4
+export type MessageType =
+  | 'subscribe'
+  | 'unsubscribe'
+  | 'listen'
+  | 0
+  | 1
+  | 2
+  | 3
+  | 4
 
 export type MType = 0 | 1 | 2 | 3 | 4
 
@@ -9,6 +17,7 @@ export type MState = 1 | 2
 
 export declare const SUBSCRIBEMessage: 'subscribe',
   UNSUBSCRIBEMessage: 'unsubscribe',
+  LISTENMessage: 'listen',
   Block: 0,
   Transaction: 1,
   Subscription: 2,

package/message.js

@@ -9,6 +9,7 @@ import {
 
 export const SUBSCRIBEMessage = 'subscribe',
   UNSUBSCRIBEMessage = 'unsubscribe',
+  LISTENMessage = 'listen',
   Block = 0,
   Transaction = 1,
   Subscription = 2,
@@ -163,6 +164,7 @@ export default class Message {
       ![
         SUBSCRIBEMessage,
         UNSUBSCRIBEMessage,
+        LISTENMessage,
         Block,
         Transaction,
         Subscription,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tchain/tcabci-read-js-client",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "TransferChain Fastest Read Network WebSocket Client",
   "homepage": "https://github.com/TransferChain/tcabci-read-js-client#readme",
   "bugs": {
@@ -26,11 +26,24 @@
     "websocket.js",
     "websocketOptions.js",
     "bytea.js",
-    "validation.js"
+    "validation.js",
+    "authority.js"
   ],
   "type": "module",
   "main": "client.js",
   "types": "client.d.ts",
+  "scripts": {
+    "format": "oxfmt ./",
+    "lint": "oxfmt ./ && oxlint --fix ./",
+    "lint:check": "oxfmt --check ./ && oxlint ./",
+    "test": "pnpm run test:unit && pnpm run test:security && pnpm run test:types",
+    "test:all": "pnpm test",
+    "test:coverage": "node --experimental-test-coverage --test test/security.test.js",
+    "test:unit": "mocha --timeout 5000 test/errors_test.js test/websocketOptions_test.js test/websocket_test.js",
+    "test:security": "node --test test/security.test.js",
+    "test:types": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 test/consumer.ts",
+    "test:integration": "mocha --timeout 7000 test/client_test.js"
+  },
   "dependencies": {
     "cockatiel": "^4.0.0",
     "reconnecting-websocket": "^4.4.0"
@@ -48,16 +61,5 @@
   "engines": {
     "node": ">=24.0.0"
   },
-  "scripts": {
-    "format": "oxfmt ./",
-    "lint": "oxfmt ./ && oxlint --fix ./",
-    "lint:check": "oxfmt --check ./ && oxlint ./",
-    "test": "pnpm run test:unit && pnpm run test:security && pnpm run test:types",
-    "test:all": "pnpm test",
-    "test:coverage": "node --experimental-test-coverage --test test/security.test.js",
-    "test:unit": "mocha --timeout 5000 test/errors_test.js test/websocketOptions_test.js test/websocket_test.js",
-    "test:security": "node --test test/security.test.js",
-    "test:types": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 test/consumer.ts",
-    "test:integration": "mocha --timeout 7000 test/client_test.js"
-  }
-}
+  "packageManager": "pnpm@12.5.1"
+}

package/types.d.ts

@@ -1,3 +1,5 @@
+import type { WSAuthorityOptions } from './authority.js'
+
 /** Immutable JSON snapshot; byte buffers are not JSON values. */
 export type JSONValue =
   | null
@@ -19,6 +21,7 @@ export interface RequestOptions {
 }
 
 export interface ClientOptions {
+  authority?: WSAuthorityOptions
   allowInsecure?: boolean
   timeoutMs?: number
   maxResponseBytes?: number

package/websocketOptions.d.ts

@@ -1,3 +1,4 @@
+import type { WSAuthorityOptions } from './authority.js'
 import { WebSocketConstructor } from './types.js'
 
 export declare type Timeout = number
@@ -71,6 +72,8 @@ export declare class Options {
 
   get customWS(): WebSocketConstructor | undefined
 
+  setAuthority(authority: WSAuthorityOptions | null): this
+
   get url(): string
 
   make(): {

package/websocketOptions.js

@@ -1,3 +1,4 @@
+import { createWSAuthorityV3 } from './authority.js'
 import { CLIENT_VERSION, endpoint, positiveInteger } from './validation.js'
 
 export const HTTPSPort = 443,
@@ -13,6 +14,7 @@ export class Options {
   _longpoll = false
   _protocols = []
   _customWS
+  _authority = null
   _endpoints = ['ws', 'longpoll']
   _version = CLIENT_VERSION
   _allowInsecure = false
@@ -280,6 +282,37 @@ export class Options {
     return this._customWS
   }
 
+  /**
+   * Configure a synchronous v3 signer. Requires a Node ws-compatible constructor
+   * supporting handshake headers; browser WebSocket cannot send these headers.
+   * @param {import('./authority.js').WSAuthorityOptions|null} authority
+   * @returns {Options}
+   */
+  setAuthority(authority) {
+    if (authority === null) {
+      this._authority = null
+
+      return this
+    }
+
+    if (
+      !authority ||
+      typeof authority.address !== 'string' ||
+      authority.address.length === 0 ||
+      authority.address.length > 2048 ||
+      /[;\r\n]/.test(authority.address) ||
+      typeof authority.sign !== 'function' ||
+      typeof this._customWS?.prototype?.on !== 'function'
+    )
+      throw new TypeError(
+        'Authority requires a Node ws-compatible constructor and signer'
+      )
+
+    this._authority = { address: authority.address, sign: authority.sign }
+
+    return this
+  }
+
   /**
    * @return {string}
    */
@@ -297,8 +330,35 @@ export class Options {
    * @return {{WebSocket: ?any, maxReconnectionDelay: number, minReconnectionDelay: number, reconnectionDelayGrowFactor: number, minUptime: number, connectionTimeout: number, maxRetries: number, maxEnqueuedMessages: number, startClosed: boolean, debug: boolean }}
    */
   make() {
+    let WS = this._customWS
+
+    if (this._authority) {
+      const Base = WS,
+        options = this
+
+      WS = class extends Base {
+        constructor(url, protocols) {
+          const authority = options._authority
+
+          if (!authority)
+            throw new Error('Websocket authority configuration released')
+
+          super(url, protocols, {
+            followRedirects: false,
+            headers: {
+              Client: `tcabci-read-js-client/${CLIENT_VERSION}`,
+              'X-Authority': createWSAuthorityV3(
+                authority.address,
+                authority.sign
+              )
+            }
+          })
+        }
+      }
+    }
+
     return {
-      ...(this._customWS ? { WebSocket: this._customWS } : {}),
+      ...(WS ? { WebSocket: WS } : {}),
       maxReconnectionDelay: this._maxConnectionDelay,
       minReconnectionDelay: this._minReconnectionDelay,
       reconnectionDelayGrowFactor: this._reconnectionDelayGrowFactor,