node-opcua-client 2.169.0 → 2.172.0

package/source/client_session_keepalive_manager.ts

@@ -12,9 +12,19 @@ import type { DataValue } from "node-opcua-data-value";
 import { checkDebugFlag, make_debugLog, make_warningLog } from "node-opcua-debug";
 import { coerceNodeId } from "node-opcua-nodeid";
 import { ClientSecureChannelLayer } from "node-opcua-secure-channel";
+import type { StatusCode } from "node-opcua-status-code";
+import { StatusCodes } from "node-opcua-status-code";
 import type { ClientSessionImpl } from "./private/client_session_impl";
 import type { IClientBase } from "./private/i_private_client";
 
+interface ServiceFaultAnnotatedError extends Error {
+    response?: {
+        responseHeader?: {
+            serviceResult?: StatusCode;
+        };
+    };
+}
+
 const serverStatusStateNodeId = coerceNodeId(VariableIds.Server_ServerStatus_State);
 
 const debugLog = make_debugLog(__filename);
@@ -24,14 +34,18 @@ const warningLog = make_warningLog(__filename);
 export interface ClientSessionKeepAliveManagerEvents {
     on(event: "keepalive", eventHandler: (lastKnownServerState: ServerState, count: number) => void): this;
     on(event: "failure", eventHandler: () => void): this;
+    on(event: "keepalive_failure", eventHandler: () => void): this;
 }
 
+const maxBackoffInterval = 60_000;
+
 export class ClientSessionKeepAliveManager extends EventEmitter implements ClientSessionKeepAliveManagerEvents {
     private readonly session: ClientSessionImpl;
     private timerId?: NodeJS.Timeout;
     private pingTimeout: number;
     private lastKnownState?: ServerState;
     private transactionInProgress = false;
+    private consecutiveFailures = 0;
     public count = 0;
     public checkInterval: number;
 
@@ -86,7 +100,9 @@ export class ClientSessionKeepAliveManager extends EventEmitter implements Clien
                 return; // stop here
             }
             if (this.timerId) {
-                const timeout = Math.max(1, this.checkInterval - delta);
+                // When delta exceeds checkInterval it is an explicit backoff requested by _ping_server;
+                // otherwise delta is the time already consumed this cycle.
+                const timeout = delta > this.checkInterval ? delta : Math.max(1, this.checkInterval - delta);
                 this.timerId = setTimeout(() => this.ping_server(), timeout);
             }
         });
@@ -153,25 +169,68 @@ export class ClientSessionKeepAliveManager extends EventEmitter implements Clien
                 (err: Error | null, dataValue?: DataValue) => {
                     this.transactionInProgress = false;
 
-                    if (err || !dataValue || !dataValue.value) {
-                        if (err) {
-                            warningLog(
-                                chalk.cyan(" warning : ClientSessionKeepAliveManager#ping_server "),
-                                chalk.yellow(err.message)
-                            );
+                    if (err) {
+                        warningLog(chalk.cyan(" warning : ClientSessionKeepAliveManager#ping_server "), chalk.yellow(err.message));
+                        const serviceFaultResponse = (err as ServiceFaultAnnotatedError).response;
+                        if (serviceFaultResponse) {
+                            const sc = serviceFaultResponse.responseHeader?.serviceResult;
+                            if (sc?.equals(StatusCodes.BadSessionIdInvalid) || sc?.equals(StatusCodes.BadSessionClosed)) {
+                                this.emit("failure");
+                                warningLog(
+                                    "Keep alive has failed, considering a network outage is in place, forcing a reconnection"
+                                );
+                                terminateConnection(session._client);
+                                resolve(0);
+                            } else {
+                                if (sc?.equals(StatusCodes.BadInvalidTimestamp)) {
+                                    // BadInvalidTimestamp (OPC UA Part 4 7.38.2, Table 178:
+                                    // "The timestamp is outside the range allowed by the Server")
+                                    // refers to the timestamp field of the RequestHeader
+                                    // (OPC UA Part 4 7.32), which the spec states is used
+                                    // "only for diagnostic and logging purposes in the Server".
+                                    //
+                                    // The server responded at the OPC UA application layer:
+                                    // the SecureChannel and Session are intact. The cause is
+                                    // clock skew between client and server; this is an
+                                    // infrastructure concern outside the scope of the keepalive
+                                    // manager.
+                                    //
+                                    // Treating this as a keepalive failure is semantically
+                                    // incorrect: the round-trip succeeded. Incrementing
+                                    // consecutiveFailures leads to unbounded exponential backoff
+                                    // and eventual session expiry server-side, triggering an
+                                    // unnecessary reconnect loop.
+                                    //
+                                    // See: https://reference.opcfoundation.org/Core/Part4/v105/docs/7.38.2
+                                    //      https://reference.opcfoundation.org/Core/Part4/v105/docs/7.32
+                                    this.consecutiveFailures = 0;
+                                    debugLog("emit keepalive (BadInvalidTimestamp: session alive, clock skew on request timestamp)");
+                                    this.emit("keepalive", this.lastKnownState ?? ServerState.Unknown, this.count);
+                                    resolve(0);
+                                    return;
+                                }
+                                this.consecutiveFailures++;
+                                warningLog("Keep alive received ServiceFault from server (session intact):", sc?.toString());
+                                this.emit("keepalive_failure");
+                                resolve(Math.min(this.checkInterval * 2 ** this.consecutiveFailures, maxBackoffInterval));
+                            }
+                        } else {
+                            this.emit("failure");
+                            warningLog("Keep alive has failed, considering a network outage is in place, forcing a reconnection");
+                            terminateConnection(session._client);
+                            resolve(0);
                         }
+                        return;
+                    }
+                    if (!dataValue || !dataValue.value) {
                         /**
                          * @event failure
                          * raised when the server is not responding or is responding with en error to
                          * the keep alive read Variable value transaction
                          */
                         this.emit("failure");
-
-                        // also simulate a connection by closing the channel abruptly from our end ...
                         warningLog("Keep alive has failed, considering a network outage is in place, forcing a reconnection");
-
                         terminateConnection(session._client);
-
                         resolve(0);
                         return;
                     }
@@ -190,6 +249,7 @@ export class ClientSessionKeepAliveManager extends EventEmitter implements Clien
                         this.lastKnownState = newState;
                         this.count++; // increase successful counter
                     }
+                    this.consecutiveFailures = 0;
                     debugLog("emit keepalive");
                     this.emit("keepalive", this.lastKnownState, this.count);
                     resolve(0);

package/source/private/client_base_impl.ts

@@ -9,8 +9,8 @@ import { withLock } from "@ster5/global-mutex";
 
 import chalk from "chalk";
 import { assert } from "node-opcua-assert";
-import { getDefaultCertificateManager, makeSubject, type OPCUACertificateManager } from "node-opcua-certificate-manager";
-import { type IOPCUASecureObjectOptions, makeApplicationUrn, OPCUASecureObject } from "node-opcua-common";
+import { getDefaultCertificateManager, type OPCUACertificateManager } from "node-opcua-certificate-manager";
+import { type ICertificateStore, InMemoryCertificateStore, type IOPCUASecureObjectOptions, makeApplicationUrn, makeSubject, OPCUASecureObject } from "node-opcua-common";
 import { type Certificate, makeSHA1Thumbprint, split_der } from "node-opcua-crypto/web";
 import { installPeriodicClockAdjustment, periodicClockAdjustment, uninstallPeriodicClockAdjustment } from "node-opcua-date-time";
 import { checkDebugFlag, make_debugLog, make_errorLog, make_warningLog } from "node-opcua-debug";
@@ -27,6 +27,7 @@ import {
     type Response as Response1,
     type SecurityPolicy
 } from "node-opcua-secure-channel";
+import type { IClientTransportFactory } from "node-opcua-transport";
 import {
     FindServersOnNetworkRequest,
     type FindServersOnNetworkRequestOptions,
@@ -228,7 +229,7 @@ function __findEndpoint(this: ClientBaseImpl, endpointUrl: string, params: FindE
 /**
  * check if certificate is trusted or untrusted
  */
-async function _verify_serverCertificate(certificateManager: OPCUACertificateManager, serverCertificate: Certificate) {
+async function _verify_serverCertificate(certificateManager: ICertificateStore, serverCertificate: Certificate) {
     const status = await certificateManager.checkCertificate(serverCertificate);
     if (!status.isGood()) {
         // c8 ignore next
@@ -387,8 +388,9 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
     private _instanceNumber: number;
     private _transportSettings: TransportSettings;
     private _transportTimeout?: number;
+    private _transportFactory?: IClientTransportFactory;
 
-    public clientCertificateManager: OPCUACertificateManager;
+    public clientCertificateManager: ICertificateStore;
 
     public isUnusable() {
         return (
@@ -430,14 +432,25 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
     }
     constructor(options?: OPCUAClientBaseOptions) {
         options = options || {};
-        if (!options.clientCertificateManager) {
-            options.clientCertificateManager = getDefaultCertificateManager("PKI");
-        }
-        options.privateKeyFile = options.privateKeyFile || options.clientCertificateManager.privateKey;
-        options.certificateFile =
-            options.certificateFile || path.join(options.clientCertificateManager.rootDir, "own/certs/client_certificate.pem");
 
-        super(options as IOPCUASecureObjectOptions);
+        if (options.certificateKeyPairProvider) {
+            // In-memory path — use a lightweight in-memory store
+            // when no cert manager was explicitly provided.
+            if (!options.clientCertificateManager) {
+                options.clientCertificateManager = new InMemoryCertificateStore();
+            }
+            super(options as IOPCUASecureObjectOptions);
+        } else {
+            // Disk path — derive cert/key paths from certificate manager
+            if (!options.clientCertificateManager) {
+                options.clientCertificateManager = getDefaultCertificateManager("PKI");
+            }
+            const cm = options.clientCertificateManager as OPCUACertificateManager;
+            options.privateKeyFile = options.privateKeyFile || cm.privateKey;
+            options.certificateFile =
+                options.certificateFile || path.join(cm.rootDir, "own/certs/client_certificate.pem");
+            super(options as IOPCUASecureObjectOptions);
+        }
 
         this._setInternalState("uninitialized");
 
@@ -450,7 +463,7 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
         // we need to delay _applicationUri initialization
         this._applicationUri = options.applicationUri || this._getBuiltApplicationUri();
 
-        this.clientCertificateManager = options.clientCertificateManager;
+        this.clientCertificateManager = options.clientCertificateManager!;
         this.clientCertificateManager.referenceCounter++;
 
         this._secureChannel = null;
@@ -502,6 +515,7 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
 
         this._transportSettings = options.transportSettings || {};
         this._transportTimeout = options.transportTimeout;
+        this._transportFactory = options.transportFactory;
     }
 
     private _cancel_reconnection(callback: ErrorCallback) {
@@ -695,6 +709,7 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
             tokenRenewalInterval: this.tokenRenewalInterval,
             transportSettings: this._transportSettings,
             transportTimeout: this._transportTimeout,
+            transportFactory: this._transportFactory,
             defaultTransactionTimeout: this.defaultTransactionTimeout
         });
         secureChannel.on("backoff", (count: number, delay: number) => {
@@ -773,7 +788,7 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
     }
 
     static async createCertificate(
-        clientCertificateManager: OPCUACertificateManager,
+        clientCertificateManager: ICertificateStore,
         certificateFile: string,
         applicationName: string,
         applicationUri: string
@@ -781,7 +796,11 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
         if (!fs.existsSync(certificateFile)) {
             const hostname = getHostname();
             // this.serverInfo.applicationUri!;
-            await clientCertificateManager.createSelfSignedCertificate({
+            // Cast is safe: createDefaultCertificate only calls
+            // this in the disk path, where the manager is always
+            // an OPCUACertificateManager.
+            const cm = clientCertificateManager as unknown as OPCUACertificateManager;
+            await cm.createSelfSignedCertificate({
                 applicationUri,
                 dns: [hostname],
                 // ip: await getIpAddresses(),
@@ -819,7 +838,9 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
                     this._getBuiltApplicationUri()
                 );
                 debugLog("privateKey      = ", this.privateKeyFile);
-                debugLog("                = ", this.clientCertificateManager.privateKey);
+                if ("privateKey" in this.clientCertificateManager) {
+                    debugLog("                = ", (this.clientCertificateManager as unknown as OPCUACertificateManager).privateKey);
+                }
                 debugLog("certificateFile = ", this.certificateFile);
                 const _certificate = this.getCertificate();
                 const _privateKey = this.getPrivateKey();
@@ -847,10 +868,16 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
             return;
         }
         await this.clientCertificateManager.initialize();
-        await this.createDefaultCertificate();
-        // c8 ignore next
-        if (!fs.existsSync(this.privateKeyFile)) {
-            throw new Error(` cannot locate private key file ${this.privateKeyFile}`);
+
+        if (this.certificateFile === "<in-memory>" || this.certificateFile === "<unknown>") {
+            // In-memory provider — cert already available, skip disk operations
+        } else {
+            // Disk path — create default cert if missing
+            await this.createDefaultCertificate();
+            // c8 ignore next
+            if (!fs.existsSync(this.privateKeyFile)) {
+                throw new Error(` cannot locate private key file ${this.privateKeyFile}`);
+            }
         }
         if (this.isUnusable()) return;
 
@@ -1001,7 +1028,10 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
             // this may happen if the Server has closed the connection abruptly for some unknown reason
             // or if the tcp connection has been broken.
             callback(
-                new Error("performMessageTransaction: No SecureChannel , connection may have been canceled abruptly by server")
+                new Error(
+                    "performMessageTransaction: No SecureChannel , connection may have been canceled abruptly by server" +
+                    " while performing " + request.schema.name
+                )
             );
             return;
         }
@@ -1479,7 +1509,9 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
                 })
                 .catch((err1: Error) => {
                     warningLog("[NODE-OPCUA-W25] client's server certificate verification has failed ", err1.message);
-                    warningLog("                 clientCertificateManager.rootDir = ", this.clientCertificateManager.rootDir);
+                    if ("rootDir" in this.clientCertificateManager) {
+                        warningLog("                 clientCertificateManager.rootDir = ", (this.clientCertificateManager as unknown as { rootDir: string }).rootDir);
+                    }
 
                     const chain = split_der(endpoint.serverCertificate);
                     warningLog(`                 server certificate chain contains ${chain.length} element(s)`);
@@ -1515,7 +1547,9 @@ export class ClientBaseImpl<Events extends OPCUAClientBaseEvents = OPCUAClientBa
                         warningLog(
                             "                 verify also that the issuer certificate is trusted and the issuer's certificate is present in the issuer.cert folder\n" +
                             "                 of the client certificate manager located in ",
-                            this.clientCertificateManager.rootDir
+                            "rootDir" in this.clientCertificateManager
+                                ? (this.clientCertificateManager as unknown as { rootDir: string }).rootDir
+                                : "<in-memory>"
                         );
                     } else {
                         warningLog(

package/source/verify.ts

@@ -1,9 +1,7 @@
-import type { OPCUACertificateManager } from "node-opcua-certificate-manager";
-import type { OPCUASecureObject } from "node-opcua-common";
+import type { ICertificateStore, OPCUASecureObject } from "node-opcua-common";
 
 import { type Certificate, exploreCertificate, explorePrivateKey, publicKeyAndPrivateKeyMatches } from "node-opcua-crypto/web";
 import { checkDebugFlag, make_debugLog, make_errorLog, make_warningLog } from "node-opcua-debug";
-import type { VerifyCertificateOptions } from "node-opcua-pki";
 
 const _doDebug = checkDebugFlag(__filename);
 const _debugLog = make_debugLog(__filename);
@@ -117,7 +115,7 @@ export function verifyIsOPCUAValidCertificate(
 export async function performCertificateSanityCheck(
     secureObject: OPCUASecureObject,
     serverOrClient: "server" | "client",
-    certificateManager: OPCUACertificateManager,
+    certificateStore: ICertificateStore,
     applicationUri: string
 ): Promise<void> {
     // verify that certificate is matching private key, and inform the developer if not
@@ -128,7 +126,6 @@ export async function performCertificateSanityCheck(
         errorLog("[NODE-OPCUA-E01] Configuration error : the certificate and the private key do not match !");
         errorLog("                  please check the configuration of the OPCUA Server");
         errorLog("                    privateKey= ", secureObject.privateKeyFile);
-        errorLog(" certificateManager.privateKey= ", certificateManager.privateKey);
         errorLog("               certificateFile= ", secureObject.certificateFile);
         throw new Error(
             "[NODE-OPCUA-E01] Configuration error : the certificate and the private key do not match ! please fix your configuration"
@@ -145,13 +142,11 @@ export async function performCertificateSanityCheck(
         );
     }
 
-    const options: VerifyCertificateOptions = {
-        acceptOutdatedCertificate: false,
-        acceptOutDatedIssuerCertificate: false,
-        acceptPendingCertificate: false
+    const options = {
+        acceptOutdatedCertificate: false
     };
 
-    const status = await certificateManager.verifyCertificate(certificate, options);
+    const status = await certificateStore.verifyCertificate(certificate, options);
 
     // BadCertificateUntrusted is expected for the application's own
     // certificate — it does not need to be in its own trust list.