refactor(binding-opcua): move cert mgt and security resolution

erossignon · erossignon · commit 269ea39376d1 · 2025-09-22T17:08:42.000+02:00
move certificate management and OPCUA security resolution to
  own files, for clarity.

  improve OCPUA Certificate manager singleton lifecycle
diff --git a/packages/binding-opcua/src/certificate-manager-singleton.ts b/packages/binding-opcua/src/certificate-manager-singleton.ts
@@ -0,0 +1,54 @@
+/********************************************************************************
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the W3C Software Notice and
+ * Document License (2015-05-13) which is available at
+ * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
+ ********************************************************************************/
+import path from "node:path";
+import { OPCUACertificateManager } from "node-opcua-certificate-manager";
+import envPath from "env-paths";
+import { createLoggers } from "@node-wot/core";
+
+const { debug } = createLoggers("binding-opcua", "opcua-protocol-client");
+
+const env = envPath("binding-opcua", { suffix: "node-wot" });
+
+/**
+ * Certificate Manager Singleton for OPCUA Binding in the WoT context.
+ *
+ */
+export class CertificateManagerSingleton {
+    private static _certificateManager: OPCUACertificateManager | null = null;
+
+    public static async getCertificateManager(): Promise<OPCUACertificateManager> {
+        if (CertificateManagerSingleton._certificateManager) {
+            return CertificateManagerSingleton._certificateManager;
+        }
+        const rootFolder = path.join(env.config, "PKI");
+        debug("OPCUA PKI folder", rootFolder);
+        const certificateManager = new OPCUACertificateManager({
+            rootFolder,
+        });
+        await certificateManager.initialize();
+        certificateManager.referenceCounter++;
+        CertificateManagerSingleton._certificateManager = certificateManager;
+        return certificateManager;
+    }
+
+    public static releaseCertificateManager(): void {
+        if (CertificateManagerSingleton._certificateManager) {
+            CertificateManagerSingleton._certificateManager.referenceCounter--;
+            // dispose is degined to free resources if referenceCounter==0;
+            CertificateManagerSingleton._certificateManager.dispose();
+            CertificateManagerSingleton._certificateManager = null;
+        }
+    }
+}
diff --git a/packages/binding-opcua/src/factory.ts b/packages/binding-opcua/src/factory.ts
@@ -16,7 +16,6 @@
 import { ProtocolClientFactory, ProtocolClient, ContentSerdes, createLoggers } from "@node-wot/core";
 import { OpcuaJSONCodec, OpcuaBinaryCodec } from "./codec";
 import { OPCUAProtocolClient } from "./opcua-protocol-client";
-import { OPCUACertificateManager } from "node-opcua-certificate-manager";
 
 const { debug } = createLoggers("binding-opcua", "factory");
 
@@ -56,12 +55,6 @@ export class OPCUAClientFactory implements ProtocolClientFactory {
                 await client.stop();
             }
         })();
-
-        OPCUAProtocolClient.releaseCertificateManager();
         return true;
     }
-
-    async getCertificateManager(): Promise<OPCUACertificateManager> {
-        return await OPCUAProtocolClient.getCertificateManager();
-    }
 }
diff --git a/packages/binding-opcua/src/opcua-protocol-client.ts b/packages/binding-opcua/src/opcua-protocol-client.ts
@@ -17,8 +17,6 @@ import { Subscription } from "rxjs/Subscription";
 import { promisify } from "util";
 import { Readable } from "stream";
 import { URL } from "url";
-import path from "path";
-import envPath from "env-paths";
 import {
     ProtocolClient,
     Content,
@@ -54,25 +52,23 @@ import {
     getBuiltInDataType,
     readNamespaceArray,
     UserIdentityInfo,
-    UserIdentityInfoUserName,
-    UserIdentityInfoX509,
 } from "node-opcua-pseudo-session";
 import { makeNodeId, NodeId, NodeIdLike, NodeIdType, resolveNodeId } from "node-opcua-nodeid";
 import { AttributeIds, BrowseDirection, makeResultMask } from "node-opcua-data-model";
 import { makeBrowsePath } from "node-opcua-service-translate-browse-path";
 import { StatusCodes } from "node-opcua-status-code";
-import { coercePrivateKeyPem, convertPEMtoDER, readPrivateKey } from "node-opcua-crypto";
+import { coercePrivateKeyPem, readPrivateKey } from "node-opcua-crypto";
 import { opcuaJsonEncodeVariant } from "node-opcua-json";
 import { Argument, BrowseDescription, BrowseResult, MessageSecurityMode, UserTokenType } from "node-opcua-types";
-import { isGoodish2, OPCUACertificateManager, ReferenceTypeIds } from "node-opcua";
+import { isGoodish2, ReferenceTypeIds } from "node-opcua";
 
 import { schemaDataValue } from "./codec";
 import { OPCUACAuthenticationScheme, OPCUAChannelSecurityScheme } from "./security_scheme";
+import { CertificateManagerSingleton } from "./certificate-manager-singleton";
+import { resolveChannelSecurity, resolvedUserIdentity } from "./opcua-security-resolver";
 
 const { debug } = createLoggers("binding-opcua", "opcua-protocol-client");
 
-const env = envPath("binding-opcua", { suffix: "node-wot" });
-
 export type Command = "Read" | "Write" | "Subscribe";
 
 export interface NodeByBrowsePath {
@@ -167,32 +163,6 @@ export class OPCUAProtocolClient implements ProtocolClient {
     private _securityPolicy: SecurityPolicy = SecurityPolicy.None;
     private _userIdentity: UserIdentityInfo = <AnonymousIdentity>{ type: UserTokenType.Anonymous };
 
-    private static _certificateManager: OPCUACertificateManager | null = null;
-
-    public static async getCertificateManager(): Promise<OPCUACertificateManager> {
-        if (OPCUAProtocolClient._certificateManager) {
-            return OPCUAProtocolClient._certificateManager;
-        }
-        const rootFolder = path.join(env.config, "PKI");
-        debug("OPCUA PKI folder", rootFolder);
-        const certificateManager = new OPCUACertificateManager({
-            rootFolder,
-        });
-        await certificateManager.initialize();
-        certificateManager.referenceCounter++;
-        OPCUAProtocolClient._certificateManager = certificateManager;
-        return certificateManager;
-    }
-
-    public static releaseCertificateManager(): void {
-        if (OPCUAProtocolClient._certificateManager) {
-            OPCUAProtocolClient._certificateManager.referenceCounter--;
-            // dispose is degined to free resources if referenceCounter==0;
-            OPCUAProtocolClient._certificateManager.dispose();
-            OPCUAProtocolClient._certificateManager = null;
-        }
-    }
-
     private async _withConnection<T>(form: OPCUAForm, next: (connection: OPCUAConnection) => Promise<T>): Promise<T> {
         const endpoint = form.href;
         const matchesScheme: boolean = endpoint?.match(/^opc.tcp:\/\//) != null;
@@ -202,7 +172,7 @@ export class OPCUAProtocolClient implements ProtocolClient {
         }
         let c: OPCUAConnectionEx | undefined = this._connections.get(endpoint);
         if (!c) {
-            const clientCertificateManager = await OPCUAProtocolClient.getCertificateManager();
+            const clientCertificateManager = await CertificateManagerSingleton.getCertificateManager();
             const client = OPCUAClient.create({
                 endpointMustExist: false,
                 connectionStrategy: {
@@ -540,57 +510,18 @@ export class OPCUAProtocolClient implements ProtocolClient {
             await connection.session.close();
             await connection.client.disconnect();
         }
-        await OPCUAProtocolClient._certificateManager?.dispose();
+        CertificateManagerSingleton.releaseCertificateManager();
     }
 
-    private setChannelSecurity(security: OPCUAChannelSecurityScheme): boolean {
-        const foundSecurity = SecurityPolicy[security.policy as keyof typeof SecurityPolicy];
-
-        if (foundSecurity === undefined) {
-            return false;
-        }
-
-        this._securityPolicy = foundSecurity;
-
-        switch (security.messageMode) {
-            case "sign":
-                this._securityMode = MessageSecurityMode.Sign;
-                break;
-            case "sign_encrypt":
-                this._securityMode = MessageSecurityMode.SignAndEncrypt;
-                break;
-            default:
-                this._securityMode = MessageSecurityMode.None;
-                break;
-        }
-
+    #setChannelSecurity(security: OPCUAChannelSecurityScheme): boolean {
+        const { messageSecurityMode, securityPolicy } = resolveChannelSecurity(security);
+        this._securityMode = messageSecurityMode;
+        this._securityPolicy = securityPolicy;
         return true;
     }
 
-    private setAuthentication(security: OPCUACAuthenticationScheme): boolean {
-        switch (security.tokenType) {
-            case "username":
-                this._userIdentity = <UserIdentityInfoUserName>{
-                    type: UserTokenType.UserName,
-                    password: security.password,
-                    userName: security.userName,
-                };
-                break;
-            case "certificate":
-                this._userIdentity = <UserIdentityInfoX509>{
-                    type: UserTokenType.Certificate,
-                    certificateData: convertPEMtoDER(security.certificate),
-                    privateKey: security.privateKey,
-                };
-                break;
-            case "anonymous":
-                this._userIdentity = <UserIdentityInfo>{
-                    type: UserTokenType.Anonymous,
-                };
-                break;
-            default:
-                return false;
-        }
+    #setAuthentication(security: OPCUACAuthenticationScheme): boolean {
+        this._userIdentity = resolvedUserIdentity(security);
         return true;
     }
 
@@ -599,10 +530,10 @@ export class OPCUAProtocolClient implements ProtocolClient {
             let success = true;
             switch (securityScheme.scheme) {
                 case "uav:channel-security":
-                    success = this.setChannelSecurity(securityScheme as OPCUAChannelSecurityScheme);
+                    success = this.#setChannelSecurity(securityScheme as OPCUAChannelSecurityScheme);
                     break;
                 case "uav:authentication":
-                    success = this.setAuthentication(securityScheme as OPCUACAuthenticationScheme);
+                    success = this.#setAuthentication(securityScheme as OPCUACAuthenticationScheme);
                     break;
                 case "combo": {
                     const combo = securityScheme as AllOfSecurityScheme | OneOfSecurityScheme;
diff --git a/packages/binding-opcua/src/opcua-security-resolver.ts b/packages/binding-opcua/src/opcua-security-resolver.ts
@@ -0,0 +1,104 @@
+/********************************************************************************
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the W3C Software Notice and
+ * Document License (2015-05-13) which is available at
+ * https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
+ ********************************************************************************/
+import {
+    MessageSecurityMode,
+    SecurityPolicy,
+    UserIdentityInfo,
+    UserIdentityInfoUserName,
+    UserIdentityInfoX509,
+    UserTokenType,
+} from "node-opcua-client";
+import { convertPEMtoDER } from "node-opcua-crypto";
+import { OPCUACAuthenticationScheme, OPCUAChannelSecurityScheme } from "./security_scheme";
+
+export interface OPCUAChannelSecuritySettings {
+    securityPolicy: SecurityPolicy;
+    messageSecurityMode: MessageSecurityMode;
+}
+
+/**
+ * Resolves the channel security settings from the given security scheme.
+ * Will throw an error if the policy or message mode is invalid.
+ * @param security The OPC UA channel security scheme.
+ * @returns The resolved channel security settings.
+ */
+export function resolveChannelSecurity(security: OPCUAChannelSecurityScheme): OPCUAChannelSecuritySettings {
+    if (security.scheme === "uav:channel-security" && security.messageMode !== "none") {
+        const securityPolicy: SecurityPolicy = SecurityPolicy[security.policy as keyof typeof SecurityPolicy];
+
+        if (securityPolicy === undefined) {
+            throw new Error(`Invalid security policy '${security.policy}'`);
+        }
+
+        let messageSecurityMode: MessageSecurityMode = MessageSecurityMode.Invalid;
+        switch (security.messageMode) {
+            case "sign":
+                messageSecurityMode = MessageSecurityMode.Sign;
+                break;
+            case "sign_encrypt":
+                messageSecurityMode = MessageSecurityMode.SignAndEncrypt;
+                break;
+            default:
+                messageSecurityMode = MessageSecurityMode.None;
+                break;
+        }
+
+        return {
+            securityPolicy,
+            messageSecurityMode,
+        };
+    } else {
+        return {
+            securityPolicy: SecurityPolicy.None,
+            messageSecurityMode: MessageSecurityMode.None,
+        };
+    }
+}
+
+/**
+ * Resolves the user identity information from the given authentication scheme.
+ * Will throw an error if the token type is invalid.
+ * @param security The OPC UA authentication scheme.
+ * @returns The resolved user identity information.
+ */
+export function resolvedUserIdentity(security: OPCUACAuthenticationScheme) {
+    let userIdentity: UserIdentityInfo;
+    switch (security.tokenType) {
+        case "username":
+            userIdentity = <UserIdentityInfoUserName>{
+                type: UserTokenType.UserName,
+                password: security.password,
+                userName: security.userName,
+            };
+            break;
+        case "certificate":
+            userIdentity = <UserIdentityInfoX509>{
+                type: UserTokenType.Certificate,
+                certificateData: convertPEMtoDER(security.certificate),
+                privateKey: security.privateKey,
+            };
+            break;
+        case "anonymous":
+        default:
+            // it is OK to use anonymous as default,
+            // as it provides the lowest privileges
+            userIdentity = <UserIdentityInfo>{
+                type: UserTokenType.Anonymous,
+            };
+            break;
+    }
+
+    return userIdentity;
+}
diff --git a/packages/binding-opcua/test/opcua-security-test.ts b/packages/binding-opcua/test/opcua-security-test.ts
@@ -24,13 +24,13 @@ import { MessageSecurityMode, OPCUAClient, OPCUAServer, SecurityPolicy } from "n
 import { coercePrivateKeyPem, readCertificate, readCertificatePEM, readPrivateKey } from "node-opcua-crypto";
 import {
     OPCUAClientFactory,
-    OPCUAProtocolClient,
     OPCUACUserNameAuthenticationScheme,
     OPCUACertificateAuthenticationScheme,
     OPCUAChannelSecurityScheme,
 } from "../src";
 
 import { startServer } from "./fixture/basic-opcua-server";
+import { CertificateManagerSingleton } from "../src/certificate-manager-singleton";
 const endpoint = "opc.tcp://localhost:7890";
 
 const { debug } = createLoggers("binding-opcua", "full-opcua-thing-test");
@@ -325,7 +325,7 @@ describe("Testing OPCUA Security Combination", () => {
 
         // exchnage certificate
         const serverCertificateManager = opcuaServer.serverCertificateManager;
-        const clientCertificateManager = await OPCUAProtocolClient.getCertificateManager();
+        const clientCertificateManager = await CertificateManagerSingleton.getCertificateManager();
 
         // Client should trust client certificate
         const serverCertificate = opcuaServer.getCertificate();

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,6 @@`
`16`	`16`	`import { ProtocolClientFactory, ProtocolClient, ContentSerdes, createLoggers } from "@node-wot/core";`
`17`	`17`	`import { OpcuaJSONCodec, OpcuaBinaryCodec } from "./codec";`
`18`	`18`	`import { OPCUAProtocolClient } from "./opcua-protocol-client";`
`19`		`-import { OPCUACertificateManager } from "node-opcua-certificate-manager";`
`20`	`19`
`21`	`20`	`const { debug } = createLoggers("binding-opcua", "factory");`
`22`	`21`
`@@ -56,12 +55,6 @@ export class OPCUAClientFactory implements ProtocolClientFactory {`
`56`	`55`	`await client.stop();`
`57`	`56`	`}`
`58`	`57`	`})();`
`59`		`-`
`60`		`- OPCUAProtocolClient.releaseCertificateManager();`
`61`	`58`	`return true;`
`62`	`59`	`}`
`63`		`-`
`64`		`- async getCertificateManager(): Promise<OPCUACertificateManager> {`
`65`		`- return await OPCUAProtocolClient.getCertificateManager();`
`66`		`- }`
`67`	`60`	`}`