node-opcua-server-configuration 2.167.0 → 2.169.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-opcua-server-configuration",
-    "version": "2.167.0",
+    "version": "2.169.0",
     "description": "pure nodejs OPCUA SDK - module server-configuration",
     "scripts": {
         "build": "tsc -b",
@@ -15,36 +15,34 @@
     "dependencies": {
         "chalk": "4.1.2",
         "memfs": "^4.57.1",
-        "node-opcua-address-space": "2.167.0",
-        "node-opcua-address-space-base": "2.167.0",
+        "node-opcua-address-space": "2.169.0",
+        "node-opcua-address-space-base": "2.169.0",
         "node-opcua-assert": "2.164.0",
-        "node-opcua-basic-types": "2.167.0",
-        "node-opcua-binary-stream": "2.167.0",
-        "node-opcua-certificate-manager": "2.167.0",
-        "node-opcua-common": "2.167.0",
+        "node-opcua-basic-types": "2.169.0",
+        "node-opcua-binary-stream": "2.169.0",
+        "node-opcua-certificate-manager": "2.169.0",
+        "node-opcua-common": "2.169.0",
         "node-opcua-constants": "2.157.0",
-        "node-opcua-crypto": "5.3.3",
-        "node-opcua-data-model": "2.167.0",
-        "node-opcua-debug": "2.165.0",
-        "node-opcua-file-transfer": "2.167.0",
+        "node-opcua-crypto": "5.3.5",
+        "node-opcua-data-model": "2.169.0",
+        "node-opcua-debug": "2.168.0",
+        "node-opcua-file-transfer": "2.169.0",
         "node-opcua-hostname": "2.167.0",
-        "node-opcua-nodeid": "2.167.0",
-        "node-opcua-pki": "6.12.0",
-        "node-opcua-pseudo-session": "2.167.0",
-        "node-opcua-secure-channel": "2.167.0",
-        "node-opcua-server": "2.167.0",
-        "node-opcua-service-translate-browse-path": "2.167.0",
-        "node-opcua-status-code": "2.167.0",
-        "node-opcua-types": "2.167.0",
-        "node-opcua-variant": "2.167.0"
+        "node-opcua-nodeid": "2.169.0",
+        "node-opcua-pki": "6.13.0",
+        "node-opcua-pseudo-session": "2.169.0",
+        "node-opcua-secure-channel": "2.169.0",
+        "node-opcua-server": "2.169.0",
+        "node-opcua-service-translate-browse-path": "2.169.0",
+        "node-opcua-status-code": "2.169.0",
+        "node-opcua-types": "2.169.0",
+        "node-opcua-variant": "2.169.0"
     },
     "devDependencies": {
-        "@types/mocha": "^10.0.10",
         "bcryptjs": "3.0.3",
-        "mocha": "11.7.5",
-        "node-opcua-client": "2.167.0",
-        "node-opcua-data-value": "2.167.0",
-        "node-opcua-leak-detector": "2.165.0",
+        "node-opcua-client": "2.169.0",
+        "node-opcua-data-value": "2.169.0",
+        "node-opcua-leak-detector": "2.169.0",
         "node-opcua-nodesets": "2.163.1"
     },
     "author": "Etienne Rossignon",
@@ -62,7 +60,7 @@
         "internet of things"
     ],
     "homepage": "http://node-opcua.github.io/",
-    "gitHead": "5decfa86ee53a36ecd3bb454e7bf6e3dd27c7a4e",
+    "gitHead": "82d570d3e95bea689cbbe30096279885c5282245",
     "files": [
         "dist",
         "source"

package/source/clientTools/push_certificate_management_client.ts

@@ -3,7 +3,7 @@
  */
 import type { ByteString } from "node-opcua-basic-types";
 import { BinaryStream } from "node-opcua-binary-stream";
-import { combine_der, type Certificate } from "node-opcua-crypto/web";
+import { type Certificate, combine_der } from "node-opcua-crypto/web";
 import { AttributeIds, coerceQualifiedName, type QualifiedNameLike } from "node-opcua-data-model";
 import { ClientFile, OpenFileMode } from "node-opcua-file-transfer";
 import { NodeId, resolveNodeId } from "node-opcua-nodeid";
@@ -141,10 +141,7 @@ export class TrustListClient extends ClientFile implements ITrustList {
         return callMethodResult.outputArguments?.[0].value as boolean;
     }
 
-    async addCertificate(
-        certificateChain: Certificate | Certificate[],
-        isTrustedCertificate: boolean
-    ): Promise<StatusCode> {
+    async addCertificate(certificateChain: Certificate | Certificate[], isTrustedCertificate: boolean): Promise<StatusCode> {
         await this.ensureInitialized();
 
         if (Array.isArray(certificateChain)) {
@@ -153,8 +150,7 @@ export class TrustListClient extends ClientFile implements ITrustList {
             }
         }
 
-        const compositeCertificate: Buffer =
-            Array.isArray(certificateChain) ? combine_der(certificateChain) : certificateChain;
+        const compositeCertificate: Buffer = Array.isArray(certificateChain) ? combine_der(certificateChain) : certificateChain;
 
         const inputArguments: VariantLike[] = [
             { dataType: DataType.ByteString, value: compositeCertificate },
@@ -223,7 +219,7 @@ export class CertificateGroup {
     constructor(
         public session: IBasicSessionAsync,
         public nodeId: NodeId
-    ) { }
+    ) {}
     async getCertificateTypes(): Promise<NodeId[]> {
         const browsePathResult = await this.session.translateBrowsePath(makeBrowsePath(this.nodeId, "/CertificateTypes"));
         if (browsePathResult.statusCode.isNotGood()) {

package/source/index.ts

@@ -6,9 +6,10 @@
 export * from "./clientTools/certificate_types.js";
 export * from "./clientTools/push_certificate_management_client.js";
 export * from "./push_certificate_manager.js";
-export * from "./server/install_push_certitifate_management.js";
+export * from "./server/install_push_certificate_management.js";
 export * from "./server/promote_trust_list.js";
 export * from "./server/push_certificate_manager/subject_to_string.js";
 export * from "./server/push_certificate_manager_helpers.js";
 export * from "./server/push_certificate_manager_server_impl.js";
+export * from "./server/trust_list_server.js";
 export * from "./standard_certificate_types.js";

package/source/server/file_transaction_manager.ts

@@ -93,6 +93,31 @@ export class FileTransactionManager {
         this.addFileOp(() => this.#moveFileWithBackupTracked(tempFilePath, destinationPath));
     }
 
+    /**
+     * Stages a file for deletion during the transaction.
+     *
+     * The file is backed up before removal so it can be restored
+     * if the transaction is rolled back.  If the file does not
+     * exist at apply time the operation is silently skipped.
+     *
+     * @param filePath - absolute path of the file to remove
+     */
+    public stageFileRemoval(filePath: string): void {
+        this.addFileOp(async () => {
+            if (!fs.existsSync(filePath)) {
+                return;
+            }
+            // Create a backup before deleting so rollback can restore it
+            const tmpDir = await this.getTmpDir();
+            const uniqueFileName = `${crypto.randomBytes(16).toString("hex")}_backup.tmp`;
+            const backupPath = path.join(tmpDir, uniqueFileName);
+            this.#backupFiles.set(filePath, backupPath);
+
+            await _copyFile(filePath, backupPath);
+            await _deleteFile(filePath);
+        });
+    }
+
     public addFileOp(functor: Functor): void {
         this.#pendingFileOps.push(functor);
     }

package/source/server/install_push_certificate_management.ts

@@ -0,0 +1,332 @@
+/**
+ * @module node-opcua-server-configuration-server
+ */
+import path from "node:path";
+
+import chalk from "chalk";
+
+import type { AddressSpace, UAServerConfiguration } from "node-opcua-address-space";
+import { assert } from "node-opcua-assert";
+import type { OPCUACertificateManager } from "node-opcua-certificate-manager";
+import { type ICertificateKeyPairProvider, invalidateCachedSecrets } from "node-opcua-common";
+import { type Certificate, split_der, exploreCertificateInfo } from "node-opcua-crypto/web";
+import { checkDebugFlag, make_debugLog, make_errorLog, make_warningLog } from "node-opcua-debug";
+import { invalidateServerCertificateCache, type OPCUAServer, type OPCUAServerEndPoint } from "node-opcua-server";
+import { type StatusCode, StatusCodes } from "node-opcua-status-code";
+import { type ApplicationDescriptionOptions, ServerState } from "node-opcua-types";
+
+import { installPushCertificateManagement } from "./push_certificate_manager_helpers.js";
+import type { ActionQueue, PushCertificateManagerServerImpl } from "./push_certificate_manager_server_impl.js";
+
+const debugLog = make_debugLog("ServerConfiguration");
+const doDebug = checkDebugFlag("ServerConfiguration");
+const errorLog = make_errorLog("ServerConfiguration");
+const warningLog = make_warningLog("ServerConfiguration");
+
+/** Relative path from cert manager root to the leaf certificate PEM. */
+const CERT_PEM_RELATIVE_PATH = "own/certs/certificate.pem";
+
+export interface OPCUAServerPartial extends ICertificateKeyPairProvider {
+    serverInfo?: ApplicationDescriptionOptions;
+    serverCertificateManager: OPCUACertificateManager;
+    privateKeyFile: string;
+    certificateFile: string;
+    engine: { addressSpace?: AddressSpace };
+    createDefaultCertificate(): Promise<void>;
+}
+
+async function onCertificateAboutToChange(server: OPCUAServer) {
+    doDebug && debugLog(chalk.yellow(" onCertificateAboutToChange => Suspending End points"));
+    await server.suspendEndPoints();
+    doDebug && debugLog(chalk.yellow(" onCertificateAboutToChange => End points suspended"));
+}
+
+/**
+ * onCertificateChange is called when the serverConfiguration notifies
+ * that the server certificate and/or private key has changed.
+ *
+ * This function invalidates all cached certificates so that new
+ * connections immediately serve the updated certificate.
+ *
+ * Channel teardown is deferred to the `applyChangesCompleted` event
+ * so the ApplyChanges OPC-UA method can return its response before
+ * the admin client's own channel is destroyed.
+ */
+async function onCertificateChange(server: OPCUAServer) {
+    doDebug && debugLog("on CertificateChanged");
+    invalidateServerCertificateCache(server);
+}
+
+/**
+ * Deferred channel restart: called after the ApplyChanges method
+ * response has been sent.  Shuts down all existing secure channels
+ * (which forces clients to reconnect with the new cert) and resumes
+ * the endpoints.
+ */
+async function onApplyChangesCompleted(server: OPCUAServer) {
+    doDebug && debugLog(chalk.yellow(" onApplyChangesCompleted => shutting down channels"));
+    await server.shutdownChannels();
+    doDebug && debugLog(chalk.yellow(" onApplyChangesCompleted => channels shut down"));
+
+    doDebug && debugLog(chalk.yellow(" onApplyChangesCompleted => resuming end points"));
+    await server.resumeEndPoints();
+    doDebug && debugLog(chalk.yellow(" onApplyChangesCompleted => end points resumed"));
+
+    debugLog(chalk.yellow("channels have been closed -> client should reconnect "));
+}
+
+/**
+ * Redirect the server's `certificateFile` and `privateKeyFile`
+ * properties to the cert manager's paths, create a default
+ * certificate if none exists, and invalidate cached secrets.
+ */
+async function install(this: OPCUAServerPartial): Promise<void> {
+    doDebug && debugLog("install push certificate management", this.serverCertificateManager.rootDir);
+
+    Object.defineProperty(this, "privateKeyFile", {
+        get: () => this.serverCertificateManager.privateKey,
+        configurable: true,
+        enumerable: true
+    });
+    Object.defineProperty(this, "certificateFile", {
+        get: () => path.join(this.serverCertificateManager.rootDir, CERT_PEM_RELATIVE_PATH),
+        configurable: true,
+        enumerable: true
+    });
+
+    // Delegate to the base server's createDefaultCertificate() which
+    // handles DNS (fqdn + hostname + configured), IPs (auto + configured),
+    // proper subject via makeSubject(), mutex locking, and file checks.
+    await this.createDefaultCertificate();
+
+    // Invalidate any previously cached secrets so that
+    // getCertificateChain() / getPrivateKey() will re-read from disk.
+    invalidateCachedSecrets(this);
+}
+
+interface UAServerConfigurationEx extends UAServerConfiguration {
+    $pushCertificateManager: PushCertificateManagerServerImpl;
+}
+
+export async function installPushCertificateManagementOnServer(server: OPCUAServer): Promise<void> {
+    if (!server.engine || !server.engine.addressSpace) {
+        throw new Error(
+            "Server must have a valid address space. " +
+            "You need to call installPushCertificateManagementOnServer after server has been initialized"
+        );
+    }
+    await install.call(server as unknown as OPCUAServerPartial);
+
+    // After install() redirected certificateFile / privateKeyFile,
+    // the SecretHolder(this) in each endpoint already follows the
+    // new paths. Just invalidate their cached values so the next
+    // access re-reads from the cert manager's files.
+    invalidateServerCertificateCache(server);
+
+    await installPushCertificateManagement(server.engine.addressSpace, {
+        applicationGroup: server.serverCertificateManager,
+        userTokenGroup: server.userCertificateManager,
+
+        applicationUri: server.serverInfo.applicationUri || "InvalidURI"
+    });
+
+    const serverConfiguration = server.engine.addressSpace.rootFolder.objects.server.getChildByName("ServerConfiguration");
+    const serverConfigurationPriv = serverConfiguration as UAServerConfigurationEx;
+    assert(serverConfigurationPriv.$pushCertificateManager);
+
+    serverConfigurationPriv.$pushCertificateManager.on("CertificateAboutToChange", (actionQueue: ActionQueue) => {
+        actionQueue.push(async (): Promise<void> => {
+            doDebug && debugLog("CertificateAboutToChange Event received");
+            await onCertificateAboutToChange(server);
+            doDebug && debugLog("CertificateAboutToChange Event processed");
+        });
+    });
+    serverConfigurationPriv.$pushCertificateManager.on("CertificateChanged", (actionQueue: ActionQueue) => {
+        actionQueue.push(async (): Promise<void> => {
+            doDebug && debugLog("CertificateChanged Event received");
+            await onCertificateChange(server);
+            doDebug && debugLog("CertificateChanged Event processed");
+        });
+    });
+
+    serverConfigurationPriv.$pushCertificateManager.on("applyChangesCompleted", () => {
+        // Fire-and-forget: schedule channel teardown + endpoint
+        // resumption AFTER the method response is sent.
+        setImmediate(async () => {
+            try {
+                await onApplyChangesCompleted(server);
+            } catch (err) {
+                errorLog("onApplyChangesCompleted error:", (err as Error).message);
+            }
+        });
+    });
+
+    // ── Install NoConfiguration certificate relaxation ─────────
+    //
+    // When the server is in NoConfiguration state (awaiting GDS
+    // provisioning), relax certain certificate trust/CRL errors
+    // so that the GDS client can connect and provision the server.
+    //
+    // This hook is ONLY installed when push certificate management
+    // is active — bare servers are completely unaffected.
+    installCertificateRelaxationHook(server);
+}
+
+// ── Certificate relaxation for NoConfiguration state ──────────
+
+/**
+ * Status codes that can be relaxed during NoConfiguration state.
+ *
+ * These represent "trust infrastructure not yet set up" situations
+ * (missing issuers, missing CRLs) — NOT security violations
+ * (revoked, expired, invalid).
+ *
+ * ### Why `BadCertificateUntrusted` MUST be included (SECURITY NOTE)
+ *
+ * In `NoConfiguration` the server's trust store is **empty** — no
+ * trusted certificates and no CRLs exist yet.  A GDS client that
+ * connects to provision the server will inevitably present a
+ * certificate that is "untrusted" simply because nothing is trusted
+ * yet.  Removing `BadCertificateUntrusted` from this list would make
+ * it impossible for the GDS to connect, breaking the entire push
+ * certificate management provisioning workflow (chicken-and-egg).
+ *
+ * **Security boundary:** this relaxation is ONLY active while the
+ * server state is `ServerState.NoConfiguration`.  Once the server
+ * transitions to `Running` (after successful provisioning) the
+ * relaxation hook returns the original status code unchanged and
+ * normal strict certificate validation applies.  The accepted
+ * certificate is auto-trusted (see `autoTrustCertificateChain`)
+ * so that subsequent connections succeed under normal validation.
+ *
+ * Errors that indicate an active security violation (revoked,
+ * expired, invalid signature, wrong usage) are **never** relaxed,
+ * even in `NoConfiguration`.
+ */
+function isRelaxableCertificateError(statusCode: StatusCode): boolean {
+    return (
+        StatusCodes.BadCertificateUntrusted.equals(statusCode) ||
+        StatusCodes.BadCertificateRevocationUnknown.equals(statusCode) ||
+        StatusCodes.BadCertificateIssuerRevocationUnknown.equals(statusCode) ||
+        StatusCodes.BadCertificateChainIncomplete.equals(statusCode)
+    );
+}
+
+/**
+ * Auto-trust the client's leaf certificate during NoConfiguration.
+ *
+ * Only the **leaf** (chain[0]) is placed in the trusted store —
+ * this is sufficient for the GDS client to reconnect after the
+ * server transitions to Running (the PKI verifier short-circuits
+ * to `Good` when the leaf itself is explicitly trusted).
+ *
+ * Issuer (CA) certificates from the chain are added to the
+ * **issuers/** store for chain-building purposes, but they do
+ * NOT become trust anchors.  This prevents a single provisioning
+ * connection from unintentionally granting trust to every
+ * certificate signed by the same CA.
+ */
+async function autoTrustCertificateChain(
+    server: OPCUAServer,
+    certificate: Certificate
+): Promise<void> {
+    let chain: Certificate[];
+    try {
+        chain = split_der(certificate);
+    } catch (err) {
+        warningLog(
+            "[NoConfiguration] Cannot parse certificate chain for auto-trust:",
+            (err as Error).message
+        );
+        return;
+    }
+
+    const cm = server.serverCertificateManager;
+
+    for (let i = 0; i < chain.length; i++) {
+        const cert = chain[i];
+        // Validate the DER structure before persisting.
+        // Garbage data (e.g. zero-filled buffers) parses into tiny blobs
+        // that are not valid X.509 certificates.
+        try {
+            exploreCertificateInfo(cert);
+        } catch (err) {
+            warningLog(
+                "[NoConfiguration] Skipping invalid certificate in chain for auto-trust:",
+                (err as Error).message
+            );
+            continue;
+        }
+
+        if (i === 0) {
+            // Leaf certificate → trust explicitly
+            try {
+                await cm.trustCertificate(cert);
+            } catch (err) {
+                // ENOENT can happen if another concurrent call already
+                // moved the cert from rejected to trusted.
+                if ((err as Error & { code?: string }).code !== "ENOENT") {
+                    warningLog(
+                        "[NoConfiguration] Failed to auto-trust leaf certificate:",
+                        (err as Error).message
+                    );
+                }
+            }
+        } else {
+            // Issuer CA certificate → add to issuers/ (chain-building
+            // only, does NOT establish a trust anchor)
+            try {
+                await cm.addIssuer(cert);
+            } catch (err) {
+                warningLog(
+                    "[NoConfiguration] Failed to add issuer certificate:",
+                    (err as Error).message
+                );
+            }
+        }
+    }
+}
+
+/**
+ * Install the `onAdjustCertificateStatus` hook on every endpoint.
+ *
+ * When the server is in `ServerState.NoConfiguration`, the hook
+ * relaxes trust/CRL errors so that a GDS client with a valid
+ * full-chain certificate can connect and provision the server.
+ *
+ * The leaf certificate is auto-trusted so that after the server
+ * transitions to Running, the same client is accepted by normal
+ * validation.  Issuer CAs are placed in `issuers/` for chain
+ * building but do not become trust anchors.
+ */
+function installCertificateRelaxationHook(server: OPCUAServer): void {
+    const adjustCertificateStatus = async (
+        statusCode: StatusCode,
+        certificate: Certificate
+    ): Promise<StatusCode> => {
+        // Only relax in NoConfiguration state
+        if (server.engine.getServerState() !== ServerState.NoConfiguration) {
+            return statusCode;
+        }
+
+        // Only relax trust-infrastructure errors, NOT security errors
+        if (!isRelaxableCertificateError(statusCode)) {
+            return statusCode;
+        }
+
+        doDebug && warningLog(
+            `[NoConfiguration] Relaxing certificate check:`,
+            `${statusCode.toString()} → Good`,
+            "(server is awaiting GDS provisioning)"
+        );
+
+        // Auto-trust the leaf certificate; issuer CAs go to issuers/
+        await autoTrustCertificateChain(server, certificate);
+
+        return StatusCodes.Good;
+    };
+
+    for (const endpoint of server.endpoints) {
+        (endpoint as OPCUAServerEndPoint).onAdjustCertificateStatus = adjustCertificateStatus;
+    }
+}