node-opcua-pki 6.22.1 → 7.0.0

package/dist/lib/pki/certificate_manager.js

@@ -0,0 +1,2302 @@
+// ---------------------------------------------------------------------------------------------------------------------
+// node-opcua-pki — CertificateManager
+// ---------------------------------------------------------------------------------------------------------------------
+// Copyright (c) 2014-2026 - Etienne Rossignon - etienne.rossignon (at) gadz.org
+// Copyright (c) 2022-2026 - Sterfive.com
+// ---------------------------------------------------------------------------------------------------------------------
+// This project is licensed under the terms of the MIT license.
+// ---------------------------------------------------------------------------------------------------------------------
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import { drainPendingLocks, withLock } from "@ster5/global-mutex";
+import chalk from "chalk";
+import chokidar from "chokidar";
+import { caSignerFromKeyOperations, exploreCertificate, exploreCertificateInfo, exploreCertificateRevocationList, generatePrivateKeyFile, keyOperationsFromPrivateKey, makeSHA1Thumbprint, PrivateKeyUnavailableError, readCertificateChain, readCertificateChainAsync, readCertificateRevocationList, readPrivateKey, split_der, toPem, verifyCertificateSignature, writePrivateKeyFile } from "node-opcua-crypto";
+import { resolvePrivateKeyPassphrase } from "../toolbox/common.js";
+import { ensurePrivateDirectory, isEncryptedPrivateKeyFile, makePath, mkdirRecursiveSync, restrictPrivateFilePermissions } from "../toolbox/common2.js";
+import { debugLog, warningLog } from "../toolbox/debug.js";
+import { createCertificateSigningRequestAsync, createSelfSignedCertificate } from "../toolbox/without_openssl/index.js";
+import _simple_config_template from "./templates/simple_config_template.cnf.js";
+/**
+ *
+ * a minimalist config file for openssl that allows
+ * self-signed certificate to be generated.
+ *
+ */
+const configurationFileSimpleTemplate = _simple_config_template;
+const fsWriteFile = fs.promises.writeFile;
+/** Return the cached `info` or compute and cache it. */
+function getOrComputeInfo(entry) {
+    if (!entry.info) {
+        entry.info = exploreCertificate(entry.certificate);
+    }
+    return entry.info;
+}
+/**
+ * OPC UA certificate verification status codes.
+ *
+ * These mirror the OPC UA `StatusCode` values for certificate
+ * validation results.
+ */
+export var VerificationStatus;
+(function (VerificationStatus) {
+    /** The certificate provided as a parameter is not valid. */
+    VerificationStatus["BadCertificateInvalid"] = "BadCertificateInvalid";
+    /** An error occurred verifying security. */
+    VerificationStatus["BadSecurityChecksFailed"] = "BadSecurityChecksFailed";
+    /** The certificate does not meet the requirements of the security policy. */
+    VerificationStatus["BadCertificatePolicyCheckFailed"] = "BadCertificatePolicyCheckFailed";
+    /** The certificate has expired or is not yet valid. */
+    VerificationStatus["BadCertificateTimeInvalid"] = "BadCertificateTimeInvalid";
+    /** An issuer certificate has expired or is not yet valid. */
+    VerificationStatus["BadCertificateIssuerTimeInvalid"] = "BadCertificateIssuerTimeInvalid";
+    /** The HostName used to connect to a server does not match a HostName in the certificate. */
+    VerificationStatus["BadCertificateHostNameInvalid"] = "BadCertificateHostNameInvalid";
+    /** The URI specified in the ApplicationDescription does not match the URI in the certificate. */
+    VerificationStatus["BadCertificateUriInvalid"] = "BadCertificateUriInvalid";
+    /** The certificate may not be used for the requested operation. */
+    VerificationStatus["BadCertificateUseNotAllowed"] = "BadCertificateUseNotAllowed";
+    /** The issuer certificate may not be used for the requested operation. */
+    VerificationStatus["BadCertificateIssuerUseNotAllowed"] = "BadCertificateIssuerUseNotAllowed";
+    /** The certificate is not trusted. */
+    VerificationStatus["BadCertificateUntrusted"] = "BadCertificateUntrusted";
+    /** It was not possible to determine if the certificate has been revoked. */
+    VerificationStatus["BadCertificateRevocationUnknown"] = "BadCertificateRevocationUnknown";
+    /** It was not possible to determine if the issuer certificate has been revoked. */
+    VerificationStatus["BadCertificateIssuerRevocationUnknown"] = "BadCertificateIssuerRevocationUnknown";
+    /** The certificate has been revoked. */
+    VerificationStatus["BadCertificateRevoked"] = "BadCertificateRevoked";
+    /** The issuer certificate has been revoked. */
+    VerificationStatus["BadCertificateIssuerRevoked"] = "BadCertificateIssuerRevoked";
+    /** The certificate chain is incomplete. */
+    VerificationStatus["BadCertificateChainIncomplete"] = "BadCertificateChainIncomplete";
+    /** Validation OK. */
+    VerificationStatus["Good"] = "Good";
+})(VerificationStatus || (VerificationStatus = {}));
+export function coerceCertificateChain(certificate) {
+    if (Array.isArray(certificate)) {
+        if (certificate.length === 0)
+            return [];
+        return certificate.reduce((acc, cert) => {
+            return acc.concat(split_der(cert));
+        }, []);
+    }
+    return split_der(certificate);
+}
+export function makeFingerprint(certificate) {
+    // When the buffer contains a certificate chain (multiple
+    // concatenated DER structures), the thumbprint must be
+    // computed on the leaf certificate only (first element).
+    const chain = coerceCertificateChain(certificate);
+    return makeSHA1Thumbprint(chain[0]).toString("hex");
+}
+function short(stringToShorten) {
+    return stringToShorten.substring(0, 10);
+}
+// Characters we keep in the human-readable part of a stored certificate
+// filename: plain ASCII letters, digits, and a few separators. Everything else
+// is dropped. The Common Name is free text supplied in the certificate, so it
+// is only ever decorative here — the fingerprint in brackets is what actually
+// identifies the file — and keeping the label to a small, known set makes the
+// name portable and predictable across file systems.
+const disallowedInLabel = /[^A-Za-z0-9._ -]/g;
+// Exported for tests; not re-exported from the package index (internal helper).
+export function toFilenameLabel(commonName) {
+    // Normalising to NFKC first lets common "wide"/decorative letter forms fold
+    // to their plain ASCII equivalent, so a legitimate name stays readable
+    // instead of collapsing into underscores. Anything left outside the allowed
+    // set becomes "_", any remaining non-ASCII is dropped, and the length is
+    // capped since the fingerprint already guarantees uniqueness.
+    const label = (commonName || "")
+        .normalize("NFKC")
+        .replace(disallowedInLabel, "_")
+        .replace(/[^\x20-\x7E]/g, "")
+        .slice(0, 64)
+        .trim();
+    return label || "certificate";
+}
+function buildIdealCertificateName(certificate) {
+    const chain = coerceCertificateChain(certificate);
+    const fingerprint = makeFingerprint(chain);
+    try {
+        const commonName = exploreCertificate(chain[0]).tbsCertificate.subject.commonName || "";
+        const sanitizedCommonName = toFilenameLabel(commonName);
+        return `${sanitizedCommonName}[${fingerprint}]`;
+    }
+    catch (_err) {
+        // make be certificate is incorrect !
+        return `invalid_certificate_[${fingerprint}]`;
+    }
+}
+// Defense-in-depth for the store layout: a certificate filename is always
+// `<label>.pem` with no path separators — `toFilenameLabel` guarantees this. This
+// helper joins a store folder with such a filename and verifies the *resolved*
+// path stays inside that folder, so a future sanitizer regression, a new call
+// site, or an unforeseen encoding can never write a certificate outside its
+// store. It fails closed (throws) rather than silently writing elsewhere.
+// Exported for tests; not re-exported from the package index (internal helper).
+export function safeStoreJoin(folder, filename) {
+    const full = path.resolve(folder, filename);
+    const base = path.resolve(folder);
+    if (full !== base && !full.startsWith(base + path.sep)) {
+        warningLog("refusing to write certificate outside its store folder:", filename);
+        throw new Error(`certificate filename escapes its store folder: ${filename}`);
+    }
+    return full;
+}
+function findMatchingIssuerKey(entries, wantedIssuerKey) {
+    return entries.filter((entry) => {
+        const info = getOrComputeInfo(entry);
+        return info.tbsCertificate.extensions && info.tbsCertificate.extensions.subjectKeyIdentifier === wantedIssuerKey;
+    });
+}
+function isSelfSigned2(info) {
+    return (info.tbsCertificate.extensions?.subjectKeyIdentifier ===
+        info.tbsCertificate.extensions?.authorityKeyIdentifier?.keyIdentifier);
+}
+function isSelfSigned3(certificate) {
+    const info = exploreCertificate(certificate);
+    return isSelfSigned2(info);
+}
+function _isIssuerInfo(info) {
+    const basicConstraints = info.tbsCertificate.extensions?.basicConstraints;
+    if (basicConstraints?.cA) {
+        return true;
+    }
+    const keyUsage = info.tbsCertificate.extensions?.keyUsage;
+    if (keyUsage?.keyCertSign) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if the provided certificate acts as an issuer (CA)
+ * @param certificate - the DER-encoded certificate
+ * @returns true if the certificate has CA basicConstraints or keyCertSign keyUsage
+ */
+export function isIssuer(certificate) {
+    try {
+        const info = exploreCertificate(certificate);
+        return _isIssuerInfo(info);
+    }
+    catch (_err) {
+        return false;
+    }
+}
+/**
+ * Check if the provided certificate acts as an intermediate issuer.
+ * An intermediate issuer is a CA certificate that is not a root CA (not self-signed).
+ * @param certificate - the DER-encoded certificate
+ * @returns true if the certificate is a CA and is not self-signed
+ */
+export function isIntermediateIssuer(certificate) {
+    try {
+        const info = exploreCertificate(certificate);
+        if (!_isIssuerInfo(info)) {
+            return false;
+        }
+        // A root CA is self-signed. If it's not self-signed, it's an intermediate CA.
+        return !isSelfSigned2(info);
+    }
+    catch (_err) {
+        return false;
+    }
+}
+/**
+ * Check if the provided certificate acts as a root issuer.
+ * A root issuer is a CA certificate that is self-signed.
+ * @param certificate - the DER-encoded certificate
+ * @returns true if the certificate is a CA and is self-signed
+ */
+export function isRootIssuer(certificate) {
+    try {
+        const info = exploreCertificate(certificate);
+        if (!_isIssuerInfo(info)) {
+            return false;
+        }
+        // A root CA is securely self-signed
+        return isSelfSigned2(info);
+    }
+    catch (_err) {
+        return false;
+    }
+}
+/**
+ * Find the issuer certificate for a given certificate within
+ * a provided certificate chain.
+ *
+ * @param certificate - the DER-encoded certificate whose issuer to find
+ * @param chain - candidate issuer certificates to search
+ * @returns the matching issuer certificate, or `null` if not found
+ */
+export function findIssuerCertificateInChain(certificate, chain) {
+    const coercedCertificate = coerceCertificateChain(certificate);
+    const firstCertificate = coercedCertificate[0];
+    if (!firstCertificate) {
+        return null;
+    }
+    const certInfo = exploreCertificate(firstCertificate);
+    // istanbul ignore next
+    if (isSelfSigned2(certInfo)) {
+        // the certificate is self signed so is it's own issuer.
+        return firstCertificate;
+    }
+    const wantedIssuerKey = certInfo.tbsCertificate.extensions?.authorityKeyIdentifier?.keyIdentifier;
+    // istanbul ignore next
+    if (!wantedIssuerKey) {
+        // Certificate has no extension 3 ! the certificate might have been generated by an old system
+        debugLog("Certificate has no extension 3");
+        return null;
+    }
+    const coercedChain = coerceCertificateChain(chain);
+    const potentialIssuers = coercedChain.filter((c) => {
+        const info = exploreCertificate(c);
+        return info.tbsCertificate.extensions && info.tbsCertificate.extensions.subjectKeyIdentifier === wantedIssuerKey;
+    });
+    if (potentialIssuers.length === 1) {
+        return potentialIssuers[0];
+    }
+    if (potentialIssuers.length > 1) {
+        debugLog("findIssuerCertificateInChain: certificate is not self-signed but has several issuers");
+        return potentialIssuers[0];
+    }
+    return null;
+}
+/**
+ * Lifecycle state of a {@link CertificateManager} instance.
+ */
+export var CertificateManagerState;
+(function (CertificateManagerState) {
+    CertificateManagerState[CertificateManagerState["Uninitialized"] = 0] = "Uninitialized";
+    CertificateManagerState[CertificateManagerState["Initializing"] = 1] = "Initializing";
+    CertificateManagerState[CertificateManagerState["Initialized"] = 2] = "Initialized";
+    CertificateManagerState[CertificateManagerState["Disposing"] = 3] = "Disposing";
+    CertificateManagerState[CertificateManagerState["Disposed"] = 4] = "Disposed";
+})(CertificateManagerState || (CertificateManagerState = {}));
+/**
+ * Manages a GDS-compliant PKI directory structure for an OPC UA
+ * application.
+ *
+ * The PKI store layout follows the OPC UA specification:
+ *
+ * ```
+ * <location>/
+ *   ├── own/
+ *   │   ├── certs/        Own certificate(s)
+ *   │   └── private/      Own private key
+ *   ├── trusted/
+ *   │   ├── certs/        Trusted peer certificates
+ *   │   └── crl/          CRLs for trusted certs
+ *   ├── rejected/         Untrusted / rejected certificates
+ *   └── issuers/
+ *       ├── certs/        CA (issuer) certificates
+ *       └── crl/          CRLs for issuer certificates
+ * ```
+ *
+ * File-system watchers keep the in-memory indexes in sync with
+ * on-disk changes. Call {@link dispose} when the instance is no
+ * longer needed to release watchers and allow the process to
+ * exit cleanly.
+ *
+ * ## Environment Variables
+ *
+ * - **`OPCUA_PKI_USE_POLLING`** — set to `"true"` to use
+ *   polling-based file watching instead of native OS events.
+ *   Useful for NFS, CIFS, Docker volumes, or other remote /
+ *   virtual file systems where native events are unreliable.
+ *
+ * - **`OPCUA_PKI_POLLING_INTERVAL`** — polling interval in
+ *   milliseconds (only effective when polling is enabled).
+ *   Clamped to the range [100, 600 000]. Defaults to
+ *   {@link folderPollingInterval} (5 000 ms).
+ *
+ * @example
+ * ```ts
+ * const cm = new CertificateManager({ location: "/var/pki" });
+ * await cm.initialize();
+ * const status = await cm.verifyCertificate(cert);
+ * await cm.dispose();
+ * ```
+ */
+// ── Chain completion result types ─────────────────────────────
+/**
+ * Status codes returned by {@link CertificateManager.completeCertificateChain}.
+ */
+export var ChainCompletionStatus;
+(function (ChainCompletionStatus) {
+    /** The chain already reached a self-signed root — no action was needed. */
+    ChainCompletionStatus["AlreadyComplete"] = "AlreadyComplete";
+    /** One or more issuer certificates were successfully appended. */
+    ChainCompletionStatus["ChainCompleted"] = "ChainCompleted";
+    /** The issuer for the last certificate in the chain could not be found
+     *  in the issuers or trusted stores. The chain is still partial. */
+    ChainCompletionStatus["IssuerNotFound"] = "IssuerNotFound";
+    /** The input chain was empty. */
+    ChainCompletionStatus["EmptyChain"] = "EmptyChain";
+    /** Chain completion was stopped because the maximum depth was reached. */
+    ChainCompletionStatus["MaxDepthReached"] = "MaxDepthReached";
+})(ChainCompletionStatus || (ChainCompletionStatus = {}));
+// ── CertificateManager ───────────────────────────────────────
+export class CertificateManager extends EventEmitter {
+    // ── Global instance registry ─────────────────────────────────
+    // Tracks all initialized CertificateManager instances so their
+    // file watchers can be closed automatically on process exit,
+    // even if the consumer forgets to call dispose().
+    static #activeInstances = new Set();
+    static #cleanupInstalled = false;
+    static #exitHandler;
+    /**
+     * Install a best-effort `exit` hook that closes any watcher
+     * still open when the process terminates.
+     *
+     * **This library never terminates the host process.** No
+     * SIGINT/SIGTERM handler is installed: deciding how (and
+     * whether) to shut down on a signal is the application's
+     * responsibility, and a listener registered here would both
+     * pre-empt the application's own graceful shutdown and
+     * silently suppress Node's default signal behaviour.
+     *
+     * Nothing here is load-bearing for process exit. The native
+     * `fs.watch` handles are `unref()`'d when the watchers are
+     * created (see `#readCertificates`), so an undisposed
+     * CertificateManager never keeps the event loop alive. This
+     * hook is only tidiness on the way out.
+     *
+     * `exit` rather than `beforeExit`: `beforeExit` fires when
+     * the loop merely drains and the loop can subsequently be
+     * resurrected, which would leave a still-in-use instance
+     * marked Disposed. `exit` is terminal, synchronous-only and
+     * cannot alter the exit code.
+     */
+    static #installExitCleanup() {
+        if (CertificateManager.#cleanupInstalled)
+            return;
+        CertificateManager.#cleanupInstalled = true;
+        const closeDanglingWatchers = () => {
+            for (const cm of CertificateManager.#activeInstances) {
+                for (const w of cm.#watchers) {
+                    try {
+                        w.close();
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                }
+                cm.#watchers.splice(0);
+                cm.state = CertificateManagerState.Disposed;
+            }
+            CertificateManager.#activeInstances.clear();
+        };
+        CertificateManager.#exitHandler = closeDanglingWatchers;
+        process.on("exit", closeDanglingWatchers);
+    }
+    /**
+     * Remove the `exit` hook once the last instance is disposed,
+     * so a library that is initialized and disposed repeatedly
+     * does not accumulate process listeners. A later
+     * `initialize()` re-arms it.
+     */
+    static #uninstallExitCleanupIfIdle() {
+        if (CertificateManager.#activeInstances.size > 0)
+            return;
+        if (CertificateManager.#exitHandler) {
+            process.removeListener("exit", CertificateManager.#exitHandler);
+            CertificateManager.#exitHandler = undefined;
+        }
+        CertificateManager.#cleanupInstalled = false;
+    }
+    /**
+     * Dispose **all** active CertificateManager instances,
+     * closing their file watchers and freeing resources.
+     *
+     * This is mainly useful in test tear-down to ensure the
+     * Node.js process can exit cleanly.
+     */
+    static async disposeAll() {
+        const instances = [...CertificateManager.#activeInstances];
+        await Promise.all(instances.map((cm) => CertificateManager.prototype.dispose.call(cm)));
+    }
+    /**
+     * Assert that all CertificateManager instances have been
+     * properly disposed. Throws an Error listing the locations
+     * of any leaked instances.
+     *
+     * Intended for use in test `afterAll()` / `afterEach()`
+     * hooks to catch missing `dispose()` calls early.
+     *
+     * @example
+     * ```ts
+     * after(() => {
+     *     CertificateManager.checkAllDisposed();
+     * });
+     * ```
+     */
+    static checkAllDisposed() {
+        if (CertificateManager.#activeInstances.size === 0)
+            return;
+        const locations = [...CertificateManager.#activeInstances].map((cm) => cm.rootDir);
+        throw new Error(`${CertificateManager.#activeInstances.size} CertificateManager instance(s) not disposed:\n  - ${locations.join("\n  - ")}`);
+    }
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * When `true` (the default), any certificate that is not
+     * already in the trusted or rejected store is automatically
+     * written to the rejected folder the first time it is seen.
+     */
+    untrustUnknownCertificate = true;
+    /** Current lifecycle state of this instance. */
+    state = CertificateManagerState.Uninitialized;
+    /** @deprecated Use {@link folderPollingInterval} instead (typo fix). */
+    folderPoolingInterval = 5000;
+    /** Interval in milliseconds for file-system polling (when enabled). */
+    get folderPollingInterval() {
+        return this.folderPoolingInterval;
+    }
+    set folderPollingInterval(value) {
+        this.folderPoolingInterval = value;
+    }
+    /** RSA key size used when generating the private key. */
+    keySize;
+    #location;
+    #watchers = [];
+    #pendingUnrefs = new Set();
+    #readCertificatesCalled = false;
+    #filenameToHash = new Map();
+    #initializingPromise;
+    #addCertValidation;
+    #disableFileWatchers;
+    #privateKeyPassphrase;
+    #privateKeyProvider;
+    #keyOperations;
+    /** The stable lazy wrap handed out by {@link getKeyOperations} for non-opaque configurations. */
+    #lazyLocalKeyOperations;
+    /**
+     * The on-disk key, decrypted once and kept for the instance's lifetime,
+     * so the passphrase (or its resolver function) is consulted at most
+     * once. Cleared by `dispose()`. Not used when a provider is configured:
+     * the provider is the authority on the current key.
+     */
+    #cachedPrivateKey;
+    #thumbs = {
+        rejected: new Map(),
+        trusted: new Map(),
+        issuers: {
+            certs: new Map()
+        },
+        crl: new Map(),
+        issuersCrl: new Map()
+    };
+    /**
+     * Create a new CertificateManager.
+     *
+     * The constructor creates the root directory if it does not
+     * exist but does **not** initialise the PKI store — call
+     * {@link initialize} before using any other method.
+     *
+     * @param options - configuration options
+     */
+    constructor(options) {
+        super();
+        options.keySize = options.keySize || 2048;
+        if (!options.location) {
+            throw new Error("CertificateManager: missing 'location' option");
+        }
+        this.#location = makePath(options.location, "");
+        this.keySize = options.keySize;
+        const v = options.addCertificateValidationOptions ?? {};
+        this.#addCertValidation = {
+            acceptExpiredCertificate: v.acceptExpiredCertificate ?? false,
+            acceptRevokedCertificate: v.acceptRevokedCertificate ?? false,
+            ignoreMissingRevocationList: v.ignoreMissingRevocationList ?? false,
+            maxChainLength: v.maxChainLength ?? 5
+        };
+        this.#disableFileWatchers = options.disableFileWatchers ?? process.env.OPCUA_PKI_DISABLE_FILE_WATCHERS === "true";
+        this.#privateKeyPassphrase = options.privateKeyPassphrase;
+        this.#privateKeyProvider = options.privateKeyProvider;
+        this.#keyOperations = options.keyOperations;
+        if (this.#keyOperations && this.#privateKeyProvider) {
+            throw new Error("CertificateManager: 'keyOperations' and 'privateKeyProvider' are mutually exclusive:" +
+                " one hides the key, the other sources its material");
+        }
+        if (this.#keyOperations && this.#privateKeyPassphrase) {
+            throw new Error("CertificateManager: 'privateKeyPassphrase' is meaningless with 'keyOperations':" +
+                " there is no key material for a passphrase to protect");
+        }
+        mkdirRecursiveSync(options.location);
+        if (!fs.existsSync(this.#location)) {
+            throw new Error(`CertificateManager cannot access location ${this.#location}`);
+        }
+    }
+    /** Path to the OpenSSL configuration file. */
+    get configFile() {
+        return path.join(this.rootDir, "own/openssl.cnf");
+    }
+    /** Root directory of the PKI store. */
+    get rootDir() {
+        return this.#location;
+    }
+    /**
+     * Path to the private key file (`own/private/private_key.pem`).
+     *
+     * Kept for backward compatibility with code that reads the key
+     * directly from disk. When a passphrase or a `privateKeyProvider` is
+     * configured, prefer {@link getPrivateKey} instead — this getter still
+     * returns the on-disk path even if a provider is configured (there may
+     * be no meaningful file in that case).
+     */
+    get privateKey() {
+        return path.join(this.rootDir, "own/private/private_key.pem");
+    }
+    /**
+     * Resolve the private key: from `privateKeyProvider` if configured,
+     * otherwise from disk (decrypting with `privateKeyPassphrase` if the
+     * key is encrypted). Fails closed — throws
+     * `PrivateKeyPassphraseRequiredError` — if the on-disk key is encrypted
+     * and no passphrase is configured, or if the wrong passphrase is
+     * configured.
+     *
+     * The on-disk key is read and decrypted once and then cached for the
+     * lifetime of this instance, so a `privateKeyPassphrase` function is
+     * called at most once (concurrent first calls share the same read). A
+     * failed read is not cached, so a caller can fix the passphrase and
+     * retry. A `privateKeyProvider` is consulted on every call: it is the
+     * authority on what the current key is.
+     */
+    async getPrivateKey() {
+        if (this.#keyOperations) {
+            throw new PrivateKeyUnavailableError("CertificateManager.getPrivateKey is not available when keyOperations is configured:" +
+                " the private key is held by the key-operations provider (HSM/KMS) and cannot be read" +
+                " — use getKeyOperations() instead");
+        }
+        if (this.#privateKeyProvider) {
+            return await this.#privateKeyProvider.getPrivateKey();
+        }
+        if (this.#cachedPrivateKey) {
+            return this.#cachedPrivateKey;
+        }
+        if (!this.#privateKeyPromise) {
+            this.#privateKeyPromise = (async () => {
+                const passphrase = await resolvePrivateKeyPassphrase(this.#privateKeyPassphrase);
+                return readPrivateKey(this.privateKey, passphrase);
+            })().then((key) => {
+                this.#cachedPrivateKey = key;
+                return key;
+            }, (err) => {
+                this.#privateKeyPromise = undefined; // not cached: allow a retry
+                throw err;
+            });
+        }
+        return await this.#privateKeyPromise;
+    }
+    /** In-flight first read of the on-disk key, so concurrent callers share one passphrase resolution. */
+    #privateKeyPromise;
+    /**
+     * True when this manager's key is opaque — configured through
+     * `keyOperations`, held by an HSM/KMS, never obtainable as material.
+     * When true, {@link getPrivateKey} throws `PrivateKeyUnavailableError`
+     * and {@link getKeyOperations} is the only way to use the key.
+     */
+    isPrivateKeyOpaque() {
+        return !!this.#keyOperations;
+    }
+    /**
+     * The key as an opaque {@link IKeyOperations} — the recommended way to
+     * *use* the private key regardless of where it lives.
+     *
+     * Returns the configured `keyOperations` object when the key is opaque.
+     * Otherwise returns a stable lazy wrap over {@link getPrivateKey}: its
+     * methods resolve the key on first use (disk read, passphrase,
+     * `privateKeyProvider` — all async), so the wrap offers no synchronous
+     * fast path; callers that need one resolve the key themselves and build
+     * a `LocalKeyOperations` over it. The wrap follows key rotation: a
+     * `privateKeyProvider` that starts returning a different key gets a
+     * fresh underlying `LocalKeyOperations`.
+     */
+    getKeyOperations() {
+        if (this.#keyOperations) {
+            return this.#keyOperations;
+        }
+        if (!this.#lazyLocalKeyOperations) {
+            let cached;
+            const resolve = async () => {
+                const key = await this.getPrivateKey();
+                // keyed by identity: the disk path always returns the cached envelope,
+                // while a provider that rotates the key yields a fresh wrap
+                if (!cached || cached.key !== key) {
+                    cached = { key, ops: keyOperationsFromPrivateKey(key) };
+                }
+                return cached.ops;
+            };
+            this.#lazyLocalKeyOperations = {
+                sign: async (data, params) => (await resolve()).sign(data, params),
+                decryptBlock: async (block, params) => (await resolve()).decryptBlock(block, params),
+                getKeyMetadata: async () => (await resolve()).getKeyMetadata(),
+                getPublicKey: async () => (await resolve()).getPublicKey()
+            };
+        }
+        return this.#lazyLocalKeyOperations;
+    }
+    /**
+     * Fail closed at `initialize()` time, not on the first certificate
+     * operation, if the key cannot actually be used: wrong/missing
+     * passphrase on an encrypted key, a broken `privateKeyProvider`, or an
+     * unreachable `keyOperations` provider (probed via `getKeyMetadata`).
+     */
+    async #probePrivateKey() {
+        if (this.#keyOperations) {
+            await this.#keyOperations.getKeyMetadata();
+            return;
+        }
+        await this.getPrivateKey();
+    }
+    /**
+     * The key to hand to a certificate-issuance primitive: the raw
+     * {@link PrivateKey} for a local configuration, or a {@link CaSigner}
+     * adapted from `keyOperations` when the key is opaque — which requires
+     * the provider to implement `getPublicKey` (the adapter says so if not).
+     */
+    async #resolveSigningKey() {
+        if (this.#keyOperations) {
+            return caSignerFromKeyOperations(this.#keyOperations);
+        }
+        return await this.getPrivateKey();
+    }
+    /**
+     * Enable, disable, or rotate the passphrase protecting the on-disk
+     * private key: decrypt with `oldPassphrase` (omit if the key is
+     * currently unencrypted), then write back encrypted with
+     * `newPassphrase` (omit to leave it unencrypted). The write goes to a
+     * temporary file in the same directory and is atomically renamed into
+     * place, so a crash mid-rotation cannot leave a partially-written key;
+     * the temporary file is removed if anything fails, so a rotation *to*
+     * plaintext can never leave a stray cleartext copy behind. Runs under
+     * the same lock as `initialize()`.
+     *
+     * This only rewrites the on-disk file — it does not update this
+     * instance's own `privateKeyPassphrase` (set at construction), and it
+     * drops this instance's cached key so that disk stays the source of
+     * truth. Construct a new `CertificateManager` with the new passphrase to
+     * continue using it afterward.
+     *
+     * Not supported when a `privateKeyProvider` is configured (there is no
+     * disk file for this method to rewrite).
+     */
+    async reencryptPrivateKey(oldPassphrase, newPassphrase) {
+        if (this.#keyOperations) {
+            throw new PrivateKeyUnavailableError("reencryptPrivateKey: not supported when keyOperations is configured — there is no key material to rewrite");
+        }
+        if (this.#privateKeyProvider) {
+            throw new Error("reencryptPrivateKey: not supported when a privateKeyProvider is configured");
+        }
+        const oldPass = await resolvePrivateKeyPassphrase(oldPassphrase);
+        const newPass = await resolvePrivateKeyPassphrase(newPassphrase);
+        await this.withLock2(async () => {
+            const privateKey = readPrivateKey(this.privateKey, oldPass);
+            await this.#rewritePrivateKeyFile(privateKey, newPass);
+        });
+        this.#cachedPrivateKey = undefined;
+        this.#privateKeyPromise = undefined;
+    }
+    /**
+     * Atomically replace the on-disk private key with `privateKey`, written
+     * as PKCS#8 (encrypted with `passphrase` if given). Temp file next to the
+     * target, `0600`, renamed into place; the temp file is unlinked on any
+     * failure so no partial or cleartext copy can be left behind.
+     * Caller must hold the lock.
+     */
+    async #rewritePrivateKeyFile(privateKey, passphrase) {
+        const tmpFilename = `${this.privateKey}.${process.pid}-${Date.now()}.tmp`;
+        try {
+            await writePrivateKeyFile(tmpFilename, privateKey, { passphrase });
+            await fs.promises.rename(tmpFilename, this.privateKey);
+        }
+        finally {
+            await fs.promises.rm(tmpFilename, { force: true });
+        }
+    }
+    /** Path to the OpenSSL random seed file. */
+    get randomFile() {
+        return path.join(this.rootDir, "./random.rnd");
+    }
+    /**
+     * Move a certificate to the rejected store.
+     * If the certificate was previously trusted, it will be removed from the trusted folder.
+     * @param certificateOrChain - the DER-encoded certificate or certificate chain
+     */
+    async rejectCertificate(certificateOrChain) {
+        await this.#moveCertificate(certificateOrChain, "rejected");
+    }
+    /**
+     * Move a certificate to the trusted store.
+     * If the certificate was previously rejected, it will be removed from the rejected folder.
+     * @param certificateOrChain - the DER-encoded certificate or certificate chain
+     */
+    async trustCertificate(certificateOrChain) {
+        await this.#moveCertificate(certificateOrChain, "trusted");
+    }
+    /**
+     * Check whether the trusted certificate store is empty.
+     *
+     * This inspects the in-memory index, which is kept in
+     * sync with the `trusted/certs/` folder by file-system
+     * watchers after {@link initialize} has been called.
+     */
+    isTrustListEmpty() {
+        return this.#thumbs.trusted.size === 0;
+    }
+    /**
+     * Return the number of certificates currently in the
+     * trusted store.
+     */
+    getTrustedCertificateCount() {
+        return this.#thumbs.trusted.size;
+    }
+    /** Path to the rejected certificates folder. */
+    get rejectedFolder() {
+        return path.join(this.rootDir, "rejected");
+    }
+    /** Path to the trusted certificates folder. */
+    get trustedFolder() {
+        return path.join(this.rootDir, "trusted/certs");
+    }
+    /** Path to the trusted CRL folder. */
+    get crlFolder() {
+        return path.join(this.rootDir, "trusted/crl");
+    }
+    /** Path to the issuer (CA) certificates folder. */
+    get issuersCertFolder() {
+        return path.join(this.rootDir, "issuers/certs");
+    }
+    /** Path to the issuer CRL folder. */
+    get issuersCrlFolder() {
+        return path.join(this.rootDir, "issuers/crl");
+    }
+    /** Path to the own certificate folder. */
+    get ownCertFolder() {
+        return path.join(this.rootDir, "own/certs");
+    }
+    get ownPrivateFolder() {
+        return path.join(this.rootDir, "own/private");
+    }
+    /**
+     * Check if a certificate is in the trusted store.
+     * If the certificate is unknown and `untrustUnknownCertificate` is set,
+     * it will be written to the rejected folder.
+     * @param certificate - the DER-encoded certificate
+     * @returns `"Good"` if trusted, `"BadCertificateUntrusted"` if rejected/unknown,
+     *   or `"BadCertificateInvalid"` if the certificate cannot be parsed.
+     */
+    async isCertificateTrusted(certificateOrCertificateChain) {
+        try {
+            const chain = coerceCertificateChain(certificateOrCertificateChain);
+            const leafCertificate = chain[0];
+            if (chain.length < 1) {
+                return "BadCertificateInvalid";
+            }
+            let fingerprint;
+            try {
+                fingerprint = makeFingerprint(chain[0]);
+            }
+            catch (_err) {
+                return "BadCertificateInvalid";
+            }
+            if (this.#thumbs.trusted.has(fingerprint)) {
+                return "Good";
+            }
+            if (!this.#thumbs.rejected.has(fingerprint)) {
+                if (!this.untrustUnknownCertificate) {
+                    return "Good";
+                }
+                // Verify structure before writing — don't persist invalid data
+                try {
+                    exploreCertificateInfo(chain[0]);
+                }
+                catch (_err) {
+                    return "BadCertificateInvalid";
+                }
+                const filename = safeStoreJoin(this.rejectedFolder, `${buildIdealCertificateName(leafCertificate)}.pem`);
+                debugLog("certificate has never been seen before and is now rejected (untrusted) ", filename);
+                await fsWriteFile(filename, toPem(chain, "CERTIFICATE"));
+                this.#thumbs.rejected.set(fingerprint, { certificate: leafCertificate, filename });
+            }
+            return "BadCertificateUntrusted";
+        }
+        catch (_err) {
+            return "BadCertificateInvalid";
+        }
+    }
+    async #innerVerifyCertificateAsync(certificateOrChain, _isIssuer, level, options) {
+        if (level >= 5) {
+            // maximum level of certificate in chain reached !
+            return VerificationStatus.BadSecurityChecksFailed;
+        }
+        const chain = coerceCertificateChain(certificateOrChain);
+        debugLog("NB CERTIFICATE IN CHAIN = ", chain.length);
+        const info = exploreCertificate(chain[0]);
+        let hasValidIssuer = false;
+        let hasTrustedIssuer = false;
+        // check if certificate is attached to a issuer
+        const hasIssuerKey = info.tbsCertificate.extensions?.authorityKeyIdentifier?.keyIdentifier;
+        debugLog("Certificate as an Issuer Key", hasIssuerKey);
+        if (hasIssuerKey) {
+            const isSelfSigned = isSelfSigned2(info);
+            debugLog("Is the Certificate self-signed  ?", isSelfSigned);
+            if (!isSelfSigned) {
+                debugLog("Is issuer found in the list of know issuers ?", "\n subjectKeyIdentifier   = ", info.tbsCertificate.extensions?.subjectKeyIdentifier, "\n authorityKeyIdentifier = ", info.tbsCertificate.extensions?.authorityKeyIdentifier?.keyIdentifier);
+                let issuerCertificate = await this.findIssuerCertificate(chain[0]);
+                if (!issuerCertificate) {
+                    // the issuer has not been found in the list of trusted certificate
+                    // may be the issuer certificate is in the chain itself ?
+                    issuerCertificate = findIssuerCertificateInChain(chain[0], chain);
+                    if (!issuerCertificate) {
+                        debugLog(" the issuer has not been found in the chain itself nor in the issuer.cert list => the chain is incomplete!");
+                        return VerificationStatus.BadCertificateChainIncomplete;
+                    }
+                    debugLog(" the issuer certificate has been found in the chain itself ! the chain is complete !");
+                }
+                else {
+                    debugLog(" the issuer certificate has been found in the issuer.cert folder !");
+                }
+                const issuerStatus = await this.#innerVerifyCertificateAsync(issuerCertificate, true, level + 1, options);
+                if (issuerStatus === VerificationStatus.BadCertificateRevocationUnknown) {
+                    // the issuer must have a CRL available .... !
+                    return VerificationStatus.BadCertificateIssuerRevocationUnknown;
+                }
+                if (issuerStatus === VerificationStatus.BadCertificateIssuerRevocationUnknown) {
+                    // the issuer must have a CRL available .... !
+                    return VerificationStatus.BadCertificateIssuerRevocationUnknown;
+                }
+                if (issuerStatus === VerificationStatus.BadCertificateTimeInvalid) {
+                    if (!options?.acceptOutDatedIssuerCertificate) {
+                        // the issuer must have valid dates ....
+                        return VerificationStatus.BadCertificateIssuerTimeInvalid;
+                    }
+                }
+                if (issuerStatus === VerificationStatus.BadCertificateUntrusted) {
+                    debugLog("warning issuerStatus = ", issuerStatus.toString(), "the issuer certificate is not trusted");
+                    // return VerificationStatus.BadSecurityChecksFailed;
+                }
+                if (issuerStatus !== VerificationStatus.Good && issuerStatus !== VerificationStatus.BadCertificateUntrusted) {
+                    // if the issuer has other issue => let's drop!
+                    return VerificationStatus.BadSecurityChecksFailed;
+                }
+                // verify that certificate was signed by issuer
+                const isCertificateSignatureOK = verifyCertificateSignature(chain[0], issuerCertificate);
+                if (!isCertificateSignatureOK) {
+                    debugLog(" the certificate was not signed by the issuer as it claim to be ! Danger");
+                    return VerificationStatus.BadSecurityChecksFailed;
+                }
+                hasValidIssuer = true;
+                // let detected if our certificate is in the revocation list
+                let revokedStatus = await this.isCertificateRevoked(chain, issuerCertificate);
+                if (revokedStatus === VerificationStatus.BadCertificateRevocationUnknown) {
+                    if (options?.ignoreMissingRevocationList) {
+                        // continue as if the certificate was not revoked
+                        revokedStatus = VerificationStatus.Good;
+                    }
+                }
+                if (revokedStatus !== VerificationStatus.Good) {
+                    // certificate is revoked !!!
+                    debugLog("revokedStatus", revokedStatus);
+                    return revokedStatus;
+                }
+                // let check if the issuer is explicitly trusted
+                const issuerTrustedStatus = await this.#checkRejectedOrTrusted(issuerCertificate);
+                debugLog("issuerTrustedStatus", issuerTrustedStatus);
+                if (issuerTrustedStatus === "unknown") {
+                    hasTrustedIssuer = false;
+                }
+                else if (issuerTrustedStatus === "trusted") {
+                    hasTrustedIssuer = true;
+                }
+                else if (issuerTrustedStatus === "rejected") {
+                    // we should never get there: this should have been detected before !!!
+                    return VerificationStatus.BadSecurityChecksFailed;
+                }
+            }
+            else {
+                // verify that certificate was signed by issuer (self in this case)
+                const isCertificateSignatureOK = verifyCertificateSignature(chain[0], chain[0]);
+                if (!isCertificateSignatureOK) {
+                    debugLog("Self-signed Certificate signature is not valid");
+                    return VerificationStatus.BadSecurityChecksFailed;
+                }
+                const revokedStatus = await this.isCertificateRevoked(chain);
+                debugLog("revokedStatus of self signed certificate:", revokedStatus);
+            }
+        }
+        const status = await this.#checkRejectedOrTrusted(chain[0]);
+        if (status === "rejected") {
+            if (!(options.acceptCertificateWithValidIssuerChain && hasValidIssuer && hasTrustedIssuer)) {
+                return VerificationStatus.BadCertificateUntrusted;
+            }
+        }
+        // Has SoftwareCertificate passed its issue date and has it not expired ?
+        // check dates
+        //
+        // exploreCertificate rather than exploreCertificateInfo: only the two
+        // dates are wanted, and exploreCertificateInfo additionally insists on
+        // an RSA-sized public key. It threw on an EC certificate, which the
+        // caller then saw as BadCertificateInvalid - a verdict about the key
+        // type, reported as if the certificate were malformed. An issuer
+        // parsed the same way, purely to be written to the debug log, made
+        // that fatal for any chain with an EC issuer in it.
+        const { validity } = exploreCertificate(chain[0]).tbsCertificate;
+        const now = new Date();
+        let isTimeInvalid = false;
+        // check that certificate is active
+        if (validity.notBefore.getTime() > now.getTime()) {
+            // certificate is not active yet
+            debugLog(`${chalk.red("certificate is invalid : certificate is not active yet !")} not before date =${validity.notBefore}`);
+            if (!options.acceptPendingCertificate) {
+                isTimeInvalid = true;
+            }
+        }
+        //  check that certificate has not expired
+        if (validity.notAfter.getTime() <= now.getTime()) {
+            // certificate is obsolete
+            debugLog(`${chalk.red("certificate is invalid : certificate has expired !")} not after date =${validity.notAfter}`);
+            if (!options.acceptOutdatedCertificate) {
+                isTimeInvalid = true;
+            }
+        }
+        if (status === "trusted") {
+            return isTimeInvalid ? VerificationStatus.BadCertificateTimeInvalid : VerificationStatus.Good;
+        }
+        // status should be "unknown" or "rejected" (bypassed) at this point
+        if (hasIssuerKey) {
+            if (!hasTrustedIssuer) {
+                return VerificationStatus.BadCertificateUntrusted;
+            }
+            if (!hasValidIssuer) {
+                return VerificationStatus.BadCertificateUntrusted;
+            }
+            if (!options.acceptCertificateWithValidIssuerChain) {
+                // strict mode: the leaf cert is not in the trusted store
+                return VerificationStatus.BadCertificateUntrusted;
+            }
+            return isTimeInvalid ? VerificationStatus.BadCertificateTimeInvalid : VerificationStatus.Good;
+        }
+        else {
+            return VerificationStatus.BadCertificateUntrusted;
+        }
+    }
+    /**
+     * Internal verification hook called by {@link verifyCertificate}.
+     *
+     * Subclasses can override this to inject additional validation
+     * logic (e.g. application-level policy checks) while still
+     * delegating to the default chain/CRL/trust verification.
+     *
+     * @param certificate - the DER-encoded certificate to verify
+     * @param options - verification options forwarded from the
+     *   public API
+     * @returns the verification status code
+     */
+    async verifyCertificateAsync(certificate, options) {
+        const chain = coerceCertificateChain(certificate);
+        for (const element of chain) {
+            try {
+                // exploreCertificate throws if the DER element is not a
+                // valid X.509 certificate (e.g. it is a CRL or some other
+                // ASN.1 structure), which is the only question being asked
+                // here. exploreCertificateInfo used to stand in for it, but
+                // it also insists on an RSA-sized public key, so every chain
+                // containing an EC certificate was reported invalid on
+                // structural grounds it never actually failed.
+                exploreCertificate(element);
+            }
+            catch (_err) {
+                return VerificationStatus.BadCertificateInvalid;
+            }
+        }
+        const status1 = await this.#innerVerifyCertificateAsync(chain, false, 0, options);
+        return status1;
+    }
+    /**
+     * Verify a certificate against the PKI trust store.
+     *
+     * This performs a full validation including trust status,
+     * issuer chain, CRL revocation checks, and time validity.
+     *
+     * @param certificate - the DER-encoded certificate to verify
+     * @param options - optional flags to relax validation rules
+     * @returns the verification status code
+     */
+    async verifyCertificate(certificate, options) {
+        // Is the  signature on the SoftwareCertificate valid .?
+        if (!certificate) {
+            // missing certificate
+            return VerificationStatus.BadSecurityChecksFailed;
+        }
+        try {
+            const status = await this.verifyCertificateAsync(certificate, options || {});
+            return status;
+        }
+        catch (error) {
+            warningLog(`verifyCertificate error: ${error.message}`);
+            return VerificationStatus.BadCertificateInvalid;
+        }
+    }
+    /**
+     * Initialize the PKI directory structure, generate the
+     * private key (if missing), and start file-system watchers.
+     *
+     * This method is idempotent — subsequent calls are no-ops.
+     * It must be called before any certificate operations.
+     */
+    async initialize() {
+        if (this.state !== CertificateManagerState.Uninitialized) {
+            return;
+        }
+        this.state = CertificateManagerState.Initializing;
+        this.#initializingPromise = this.#initialize();
+        try {
+            await this.#initializingPromise;
+        }
+        catch (err) {
+            // Fail closed but not stuck: a failed initialize() (typically a
+            // wrong or missing private-key passphrase) must leave the
+            // instance re-initializable, not parked in Initializing where a
+            // retry would silently no-op with empty trust indexes.
+            this.#initializingPromise = undefined;
+            this.state = CertificateManagerState.Uninitialized;
+            throw err;
+        }
+        this.#initializingPromise = undefined;
+        this.state = CertificateManagerState.Initialized;
+        // Register for automatic cleanup on process exit
+        CertificateManager.#activeInstances.add(this);
+        CertificateManager.#installExitCleanup();
+    }
+    async #initialize() {
+        const pkiDir = this.#location;
+        mkdirRecursiveSync(pkiDir);
+        mkdirRecursiveSync(path.join(pkiDir, "own"));
+        mkdirRecursiveSync(path.join(pkiDir, "own/certs"));
+        ensurePrivateDirectory(path.join(pkiDir, "own/private"));
+        mkdirRecursiveSync(path.join(pkiDir, "rejected"));
+        mkdirRecursiveSync(path.join(pkiDir, "trusted"));
+        mkdirRecursiveSync(path.join(pkiDir, "trusted/certs"));
+        mkdirRecursiveSync(path.join(pkiDir, "trusted/crl"));
+        mkdirRecursiveSync(path.join(pkiDir, "issuers"));
+        mkdirRecursiveSync(path.join(pkiDir, "issuers/certs")); // contains Trusted CA certificates
+        mkdirRecursiveSync(path.join(pkiDir, "issuers/crl")); // contains CRL of revoked CA certificates
+        // when a privateKeyProvider or keyOperations is configured it overrides disk
+        // entirely, so there is no on-disk key to generate, encrypt, or check for existence
+        const ownsDiskKey = !this.#privateKeyProvider && !this.#keyOperations;
+        const needsKeyGeneration = ownsDiskKey && !fs.existsSync(this.privateKey);
+        // Secure by default: a passphrase configured on an install whose key
+        // is still plaintext means "protect this key", not "ignore me". Node's
+        // createPrivateKey would silently accept the plaintext key with any
+        // passphrase, so detect it here and encrypt in place.
+        const needsKeyEncryption = ownsDiskKey &&
+            !needsKeyGeneration &&
+            this.#privateKeyPassphrase !== undefined &&
+            !isEncryptedPrivateKeyFile(this.privateKey);
+        if (!fs.existsSync(this.configFile) || needsKeyGeneration || needsKeyEncryption) {
+            return await this.withLock2(async () => {
+                if (this.state === CertificateManagerState.Disposing || this.state === CertificateManagerState.Disposed) {
+                    return;
+                }
+                if (!fs.existsSync(this.configFile)) {
+                    fs.writeFileSync(this.configFile, configurationFileSimpleTemplate);
+                }
+                // note : openssl 1.1.1 has a bug that causes a failure if
+                // random file cannot be found. (should be fixed in 1.1.1.a)
+                // if this issue become important we may have to consider checking that rndFile exists and recreate
+                // it if not . this could be achieved with the command :
+                //      "openssl rand -writerand ${this.randomFile}"
+                //
+                // cf: https://github.com/node-opcua/node-opcua/issues/554
+                if (ownsDiskKey && !fs.existsSync(this.privateKey)) {
+                    debugLog("generating private key ...");
+                    //   setEnv("RANDFILE", this.randomFile);
+                    const passphrase = await resolvePrivateKeyPassphrase(this.#privateKeyPassphrase);
+                    await generatePrivateKeyFile(this.privateKey, this.keySize, { passphrase });
+                    // seed the cache from the passphrase we already resolved,
+                    // so a passphrase function is not called a second time below
+                    this.#cachedPrivateKey = readPrivateKey(this.privateKey, passphrase);
+                }
+                else if (ownsDiskKey && this.#privateKeyPassphrase !== undefined && !isEncryptedPrivateKeyFile(this.privateKey)) {
+                    // (re-checked under the lock: another instance may have done it first)
+                    warningLog("initialize: private key is plaintext but a passphrase is configured; encrypting it in place");
+                    const passphrase = await resolvePrivateKeyPassphrase(this.#privateKeyPassphrase);
+                    const plaintextKey = readPrivateKey(this.privateKey);
+                    await this.#rewritePrivateKeyFile(plaintextKey, passphrase);
+                    this.#cachedPrivateKey = plaintextKey;
+                }
+                if (ownsDiskKey) {
+                    // repair permissions on installs created before this hardening,
+                    // and confirm them on a freshly generated key
+                    restrictPrivateFilePermissions(this.privateKey, 0o600);
+                }
+                await this.#probePrivateKey();
+                await this.#readCertificates();
+            });
+        }
+        else {
+            if (ownsDiskKey) {
+                restrictPrivateFilePermissions(this.privateKey, 0o600);
+            }
+            await this.#probePrivateKey();
+            await this.#readCertificates();
+        }
+    }
+    /**
+     * Dispose of the CertificateManager, releasing file watchers
+     * and other resources. The instance should not be used after
+     * calling this method.
+     */
+    async dispose() {
+        if (this.state === CertificateManagerState.Disposing) {
+            throw new Error("Already disposing");
+        }
+        if (this.state === CertificateManagerState.Uninitialized) {
+            this.state = CertificateManagerState.Disposed;
+            return;
+        }
+        // Wait for initialization to complete before disposing
+        if (this.state === CertificateManagerState.Initializing) {
+            if (this.#initializingPromise) {
+                await this.#initializingPromise;
+            }
+        }
+        try {
+            this.state = CertificateManagerState.Disposing;
+            // Wait for any in-flight withLock operations (e.g.
+            // fire-and-forget trustCertificate calls) to complete
+            // so their setInterval timers are properly cleared.
+            await drainPendingLocks();
+            // Ensure all fs.watch handles are unref'd even if
+            // chokidar hasn't reached "ready" yet.
+            for (const unreff of this.#pendingUnrefs) {
+                unreff();
+            }
+            this.#pendingUnrefs.clear();
+            await Promise.all(this.#watchers.map((w) => w.close()));
+            this.#watchers.forEach((w) => {
+                w.removeAllListeners();
+            });
+            this.#watchers.splice(0);
+        }
+        finally {
+            this.state = CertificateManagerState.Disposed;
+            this.#cachedPrivateKey = undefined;
+            this.#privateKeyPromise = undefined;
+            CertificateManager.#activeInstances.delete(this);
+            CertificateManager.#uninstallExitCleanupIfIdle();
+        }
+    }
+    /**
+     * Force a full re-scan of all PKI folders, rebuilding
+     * the in-memory `_thumbs` index from scratch.
+     *
+     * Call this after external processes have modified the
+     * PKI folders (e.g. via `writeTrustList` or CLI tools)
+     * to ensure the CertificateManager sees the latest
+     * state without waiting for file-system events.
+     */
+    async reloadCertificates() {
+        // Close existing watchers
+        await Promise.all(this.#watchers.map((w) => w.close()));
+        for (const w of this.#watchers) {
+            w.removeAllListeners();
+        }
+        this.#watchers.splice(0);
+        // Clear in-memory indexes
+        this.#thumbs.rejected.clear();
+        this.#thumbs.trusted.clear();
+        this.#thumbs.issuers.certs.clear();
+        this.#thumbs.crl.clear();
+        this.#thumbs.issuersCrl.clear();
+        this.#filenameToHash.clear();
+        // Re-scan all folders
+        this.#readCertificatesCalled = false;
+        await this.#readCertificates();
+    }
+    async withLock2(action) {
+        const lockFileName = path.join(this.rootDir, "mutex");
+        return withLock({ fileToLock: lockFileName }, async () => {
+            return await action();
+        });
+    }
+    /**
+     * Create a self-signed certificate for this PKI's private key.
+     *
+     * The certificate is written to `params.outputFile` or
+     * `own/certs/self_signed_certificate.pem` by default.
+     *
+     * @param params - certificate parameters (subject, SANs,
+     *   validity, etc.)
+     */
+    async createSelfSignedCertificate(params) {
+        if (typeof params.applicationUri !== "string") {
+            throw new Error("createSelfSignedCertificate: expecting applicationUri to be a string");
+        }
+        if (!this.#privateKeyProvider && !this.#keyOperations && !fs.existsSync(this.privateKey)) {
+            throw new Error(`Cannot find private key ${this.privateKey}`);
+        }
+        let certificateFilename = path.join(this.rootDir, "own/certs/self_signed_certificate.pem");
+        certificateFilename = params.outputFile || certificateFilename;
+        // a copy, not an in-place mutation: the caller's object must never
+        // end up holding the resolved private key material
+        const _params = {
+            ...params,
+            rootDir: this.rootDir,
+            configFile: this.configFile,
+            privateKey: await this.#resolveSigningKey(),
+            subject: params.subject || "CN=FIXME"
+        };
+        await this.withLock2(async () => {
+            await createSelfSignedCertificate(certificateFilename, _params);
+        });
+    }
+    /**
+     * Create a Certificate Signing Request (CSR) using this
+     * PKI's private key and configuration.
+     *
+     * The CSR file is written to `own/certs/` with a timestamped
+     * filename.
+     *
+     * @param params - CSR parameters (subject, SANs)
+     * @returns the filesystem path to the generated CSR file
+     */
+    async createCertificateRequest(params) {
+        if (!params) {
+            throw new Error("params is required");
+        }
+        if (Object.prototype.hasOwnProperty.call(params, "rootDir")) {
+            throw new Error("rootDir should not be specified ");
+        }
+        // a copy, not an in-place mutation: the caller's object must never
+        // end up holding the resolved private key material
+        const _params = {
+            ...params,
+            rootDir: path.resolve(this.rootDir),
+            configFile: path.resolve(this.configFile),
+            privateKey: await this.#resolveSigningKey()
+        };
+        return await this.withLock2(async () => {
+            // compose a file name for the request
+            const now = new Date();
+            const today = `${now.toISOString().slice(0, 10)}_${now.getTime()}`;
+            const certificateSigningRequestFilename = path.join(this.rootDir, "own/certs", `certificate_${today}.csr`);
+            await createCertificateSigningRequestAsync(certificateSigningRequestFilename, _params);
+            return certificateSigningRequestFilename;
+        });
+    }
+    /**
+     * Add a CA (issuer) certificate to the issuers store.
+     * If the certificate is already present, this is a no-op.
+     * @param certificate - the DER-encoded CA certificate
+     * @param validate - if `true`, verify the certificate before adding
+     * @param addInTrustList - if `true`, also add to the trusted store
+     * @returns `VerificationStatus.Good` on success
+     */
+    async addIssuer(certificate, validate = false, addInTrustList = false) {
+        if (validate) {
+            const status = await this.verifyCertificate(certificate);
+            if (status !== VerificationStatus.Good && status !== VerificationStatus.BadCertificateUntrusted) {
+                return status;
+            }
+        }
+        const pemCertificate = toPem(certificate, "CERTIFICATE");
+        const fingerprint = makeFingerprint(certificate);
+        if (this.#thumbs.issuers.certs.has(fingerprint)) {
+            // already in .. simply ignore
+            return VerificationStatus.Good;
+        }
+        // write certificate
+        const filename = safeStoreJoin(this.issuersCertFolder, `issuer_${buildIdealCertificateName(certificate)}.pem`);
+        await fs.promises.writeFile(filename, pemCertificate, "ascii");
+        // first time seen, let's save it.
+        this.#thumbs.issuers.certs.set(fingerprint, { certificate, filename });
+        if (addInTrustList) {
+            // add certificate in the trust list as well
+            await this.trustCertificate(certificate);
+        }
+        return VerificationStatus.Good;
+    }
+    /**
+     * Add multiple CA (issuer) certificates to the issuers store.
+     * @param certificates - the DER-encoded CA certificates
+     * @param validate - if `true`, verify each certificate before adding
+     * @param addInTrustList - if `true`, also add each certificate to the trusted store
+     * @returns `VerificationStatus.Good` on success
+     */
+    async addIssuers(certificates, validate = false, addInTrustList = false) {
+        for (const certificate of certificates) {
+            // check that certificate is a issuer certificate
+            if (!isIssuer(certificate)) {
+                warningLog(`Certificate ${makeFingerprint(certificate)} is not a issuer certificate`);
+                continue;
+            }
+            await this.addIssuer(certificate, validate, addInTrustList);
+        }
+        return VerificationStatus.Good;
+    }
+    /**
+     * Add a CRL to the certificate manager.
+     * @param crl - the CRL to add
+     * @param target - "issuers" (default) writes to issuers/crl, "trusted" writes to trusted/crl
+     */
+    async addRevocationList(crl, target = "issuers") {
+        return await this.withLock2(async () => {
+            try {
+                const index = target === "trusted" ? this.#thumbs.crl : this.#thumbs.issuersCrl;
+                const folder = target === "trusted" ? this.crlFolder : this.issuersCrlFolder;
+                const crlInfo = exploreCertificateRevocationList(crl);
+                const key = crlInfo.tbsCertList.issuerFingerprint;
+                if (!index.has(key)) {
+                    index.set(key, { crls: [], serialNumbers: {} });
+                }
+                const pemCertificate = toPem(crl, "X509 CRL");
+                // Use the issuer fingerprint for the filename — NOT buildIdealCertificateName()
+                // which expects a certificate, not a CRL. Passing a CRL causes
+                // exploreCertificate() to throw, producing "invalid_certificate_" names.
+                const sanitizedKey = key.replace(/:/g, "");
+                const filename = path.join(folder, `crl_[${sanitizedKey}].pem`);
+                await fs.promises.writeFile(filename, pemCertificate, "ascii");
+                await this.#onCrlFileAdded(index, filename);
+                await this.#waitAndCheckCRLProcessingStatus();
+                return VerificationStatus.Good;
+            }
+            catch (err) {
+                debugLog(err);
+                return VerificationStatus.BadSecurityChecksFailed;
+            }
+        });
+    }
+    /**
+     * Remove all CRL files from the specified folder(s) and clear the
+     * corresponding in-memory index.
+     * @param target - "issuers" clears issuers/crl, "trusted" clears
+     *   trusted/crl, "all" clears both.
+     */
+    async clearRevocationLists(target) {
+        const clearFolder = async (folder, index) => {
+            try {
+                const files = await fs.promises.readdir(folder);
+                for (const file of files) {
+                    const ext = path.extname(file).toLowerCase();
+                    if (ext === ".crl" || ext === ".pem" || ext === ".der") {
+                        await fs.promises.unlink(path.join(folder, file));
+                    }
+                }
+            }
+            catch (err) {
+                if (err.code !== "ENOENT") {
+                    throw err;
+                }
+            }
+            index.clear();
+        };
+        if (target === "issuers" || target === "all") {
+            await clearFolder(this.issuersCrlFolder, this.#thumbs.issuersCrl);
+        }
+        if (target === "trusted" || target === "all") {
+            await clearFolder(this.crlFolder, this.#thumbs.crl);
+        }
+    }
+    /**
+     * Check whether an issuer certificate with the given thumbprint
+     * is already registered.
+     * @param thumbprint - hex-encoded SHA-1 thumbprint (lowercase)
+     */
+    async hasIssuer(thumbprint) {
+        await this.#readCertificates();
+        const normalized = thumbprint.toLowerCase();
+        return this.#thumbs.issuers.certs.has(normalized);
+    }
+    /**
+     * Remove a trusted certificate identified by its SHA-1 thumbprint.
+     * Deletes the file on disk and removes the entry from the
+     * in-memory index.
+     * @param thumbprint - hex-encoded SHA-1 thumbprint (lowercase)
+     * @returns the removed certificate buffer, or `null` if not found
+     */
+    async removeTrustedCertificate(thumbprint) {
+        await this.#readCertificates();
+        const normalized = thumbprint.toLowerCase();
+        const entry = this.#thumbs.trusted.get(normalized);
+        if (!entry) {
+            return null;
+        }
+        try {
+            await fs.promises.unlink(entry.filename);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw err;
+            }
+        }
+        this.#thumbs.trusted.delete(normalized);
+        return entry.certificate;
+    }
+    /**
+     * Remove an issuer certificate identified by its SHA-1 thumbprint.
+     * Deletes the file on disk and removes the entry from the
+     * in-memory index.
+     * @param thumbprint - hex-encoded SHA-1 thumbprint (lowercase)
+     * @returns the removed certificate buffer, or `null` if not found
+     */
+    async removeIssuer(thumbprint) {
+        await this.#readCertificates();
+        const normalized = thumbprint.toLowerCase();
+        const entry = this.#thumbs.issuers.certs.get(normalized);
+        if (!entry) {
+            return null;
+        }
+        try {
+            await fs.promises.unlink(entry.filename);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw err;
+            }
+        }
+        this.#thumbs.issuers.certs.delete(normalized);
+        return entry.certificate;
+    }
+    /**
+     * Remove all CRL files that were issued by the given CA certificate
+     * from the specified folder (or both).
+     * @param issuerCertificate - the CA certificate whose CRLs to remove
+     * @param target - "issuers", "trusted", or "all" (default "all")
+     */
+    async removeRevocationListsForIssuer(issuerCertificate, target = "all") {
+        const issuerInfo = exploreCertificate(issuerCertificate);
+        const issuerFingerprint = issuerInfo.tbsCertificate.subjectFingerPrint;
+        const processIndex = async (index) => {
+            const crlData = index.get(issuerFingerprint);
+            if (!crlData)
+                return;
+            for (const crlEntry of crlData.crls) {
+                try {
+                    await fs.promises.unlink(crlEntry.filename);
+                }
+                catch (err) {
+                    if (err.code !== "ENOENT") {
+                        throw err;
+                    }
+                }
+            }
+            index.delete(issuerFingerprint);
+        };
+        if (target === "issuers" || target === "all") {
+            await processIndex(this.#thumbs.issuersCrl);
+        }
+        if (target === "trusted" || target === "all") {
+            await processIndex(this.#thumbs.crl);
+        }
+    }
+    /**
+     * Validate a certificate (optionally with its chain) and add
+     * the leaf certificate to the trusted store.
+     *
+     * Performs OPC UA Part 4, Table 100 validation:
+     *
+     * 1. **Certificate Structure** — parse the DER encoding.
+     * 2. **Build Certificate Chain** — walk from the leaf to a
+     *    self-signed root CA, using the provided chain and the
+     *    issuers store.
+     * 3. **Signature** — verify each certificate's signature
+     *    against its issuer.
+     * 4. **Issuer Presence** — every issuer in the chain must
+     *    already be registered in the issuers store (per GDS
+     *    7.8.2.6).
+     * 5. **Validity Period** — each certificate must be within
+     *    its validity window (overridable via
+     *    {@link AddCertificateValidationOptions.acceptExpiredCertificate}).
+     * 6. **Revocation Check** — each certificate is checked
+     *    against its issuer's CRL (overridable via
+     *    {@link AddCertificateValidationOptions.acceptRevokedCertificate}
+     *    and {@link AddCertificateValidationOptions.ignoreMissingRevocationList}).
+     *
+     * Only the leaf certificate is added to the trusted store.
+     *
+     * @param certificateChain - DER-encoded certificate or chain
+     * @returns `VerificationStatus.Good` on success, or an error
+     *  status indicating why the certificate was rejected.
+     */
+    async addTrustedCertificateFromChain(certificateChain) {
+        // Top-level guard: never let an unexpected error escape.
+        // Every code path returns a VerificationStatus; unexpected
+        // throws (corrupt buffers, crypto failures, etc.) are
+        // caught here and mapped to BadCertificateInvalid.
+        try {
+            return await this.#addTrustedCertificateFromChainImpl(certificateChain);
+        }
+        catch (_err) {
+            warningLog("addTrustedCertificateFromChain: unexpected error", _err);
+            return VerificationStatus.BadCertificateInvalid;
+        }
+    }
+    async #addTrustedCertificateFromChainImpl(certificateChain) {
+        let certificates;
+        try {
+            certificates = coerceCertificateChain(certificateChain);
+        }
+        catch (_err) {
+            return VerificationStatus.BadCertificateInvalid;
+        }
+        if (certificates.length === 0) {
+            return VerificationStatus.BadCertificateInvalid;
+        }
+        const leafCertificate = certificates[0];
+        const opts = this.#addCertValidation;
+        // ── Step 1: Certificate Structure ────────────────────────
+        let leafInfo;
+        try {
+            leafInfo = exploreCertificate(leafCertificate);
+        }
+        catch (_err) {
+            return VerificationStatus.BadCertificateInvalid;
+        }
+        // Re-scan the issuers folder to pick up certificates
+        // added directly to disk (e.g. by GDS push or external
+        // tooling) that the file-system watcher may not have
+        // delivered yet.
+        await this.#scanCertFolder(this.issuersCertFolder, this.#thumbs.issuers.certs);
+        // ── Step 2–6: Walk the chain from leaf to root ───────────
+        // depth counts the number of certificates validated in the
+        // chain.  maxChainLength=1 → only self-signed certs;
+        // maxChainLength=2 → leaf + root CA; etc.
+        let currentCert = leafCertificate;
+        let currentInfo = leafInfo;
+        let depth = 0;
+        while (true) {
+            depth++;
+            if (depth > opts.maxChainLength) {
+                // Chain depth exceeded before reaching root
+                return VerificationStatus.BadSecurityChecksFailed;
+            }
+            // ── Step 5: Validity Period ──────────────────────────
+            if (!opts.acceptExpiredCertificate) {
+                // currentInfo is kept in lockstep with currentCert, so the
+                // dates are already parsed. Re-reading them through
+                // exploreCertificateInfo cost a second parse and rejected any
+                // EC certificate outright, since that helper also insists on
+                // an RSA-sized public key.
+                const { validity } = currentInfo.tbsCertificate;
+                const now = new Date();
+                if (validity.notBefore.getTime() > now.getTime()) {
+                    return VerificationStatus.BadCertificateTimeInvalid;
+                }
+                if (validity.notAfter.getTime() <= now.getTime()) {
+                    return depth === 1
+                        ? VerificationStatus.BadCertificateTimeInvalid
+                        : VerificationStatus.BadCertificateIssuerTimeInvalid;
+                }
+            }
+            // ── Self-signed certificate ──────────────────────────
+            if (isSelfSigned2(currentInfo)) {
+                // Step 3: Verify self-signature
+                try {
+                    if (!verifyCertificateSignature(currentCert, currentCert)) {
+                        return VerificationStatus.BadCertificateInvalid;
+                    }
+                }
+                catch (_err) {
+                    return VerificationStatus.BadCertificateInvalid;
+                }
+                // Self-signed certificates don't need revocation
+                // or issuer checks — we're at the root.
+                break;
+            }
+            // ── Step 2: Find issuer ──────────────────────────────
+            // First try findIssuerCertificate (checks issuers store
+            // and trusted store), then fall back to the chain.
+            let issuerCert = await this.findIssuerCertificate(currentCert);
+            if (!issuerCert) {
+                // The issuer is not in the issuers store — try
+                // the explicitly provided chain.
+                issuerCert = findIssuerCertificateInChain(currentCert, certificates);
+                if (!issuerCert || issuerCert === currentCert) {
+                    return VerificationStatus.BadCertificateChainIncomplete;
+                }
+            }
+            // ── Step 3: Signature verification ───────────────────
+            try {
+                if (!verifyCertificateSignature(currentCert, issuerCert)) {
+                    return VerificationStatus.BadCertificateInvalid;
+                }
+            }
+            catch (_err) {
+                return VerificationStatus.BadCertificateInvalid;
+            }
+            // ── Step 4: Issuer must be in the issuers store ──────
+            // Per GDS 7.8.2.6: "This Method will return a
+            // validation error if the Certificate is issued by a CA
+            // and the Certificate for the issuer is not in the
+            // TrustList"
+            const issuerThumbprint = makeFingerprint(issuerCert);
+            if (!(await this.hasIssuer(issuerThumbprint))) {
+                return VerificationStatus.BadCertificateChainIncomplete;
+            }
+            // ── Step 6: Revocation check ─────────────────────────
+            const revokedStatus = await this.isCertificateRevoked(currentCert, issuerCert);
+            if (revokedStatus === VerificationStatus.BadCertificateRevoked) {
+                if (!opts.acceptRevokedCertificate) {
+                    return VerificationStatus.BadCertificateRevoked;
+                }
+            }
+            else if (revokedStatus === VerificationStatus.BadCertificateRevocationUnknown) {
+                if (!opts.ignoreMissingRevocationList) {
+                    return VerificationStatus.BadCertificateRevocationUnknown;
+                }
+            }
+            // Move up the chain
+            currentCert = issuerCert;
+            try {
+                currentInfo = exploreCertificate(currentCert);
+            }
+            catch (_err) {
+                return VerificationStatus.BadCertificateInvalid;
+            }
+        }
+        // All checks passed — trust the leaf certificate.
+        // Pass the full chain so the PEM on disk preserves
+        // intermediate CA certificates (chain-on-disk,
+        // leaf-only-in-memory principle).
+        await this.trustCertificate(certificates);
+        return VerificationStatus.Good;
+    }
+    /**
+     * Check whether an issuer certificate is still needed by any
+     * certificate in the trusted store.
+     *
+     * This is used before removing an issuer to ensure that
+     * doing so would not break the chain of any trusted
+     * certificate.
+     *
+     * @param issuerCertificate - the CA certificate to check
+     * @returns `true` if at least one trusted certificate was
+     *   signed by this issuer.
+     */
+    async isIssuerInUseByTrustedCertificate(issuerCertificate) {
+        await this.#readCertificates();
+        for (const entry of this.#thumbs.trusted.values()) {
+            if (!entry.certificate)
+                continue;
+            try {
+                if (verifyCertificateSignature(entry.certificate, issuerCertificate)) {
+                    return true;
+                }
+            }
+            catch (_err) {
+                // Skip certificates that can't be verified
+            }
+        }
+        return false;
+    }
+    /**
+     *  find the issuer certificate among the trusted  issuer certificates.
+     *
+     *  The findIssuerCertificate method is an asynchronous method that attempts to find
+     *  the issuer certificate for a given certificate from the list of issuer certificate declared in the PKI
+     *
+     *  - If the certificate is self-signed, it returns the certificate itself.
+     *
+     *  - If the certificate has no extension 3, it is assumed to be generated by an old system, and a null value is returned.
+     *
+     *  - the method checks both issuer and trusted certificates and returns the appropriate issuercertificate,
+     *    if found. If multiple matching certificates are found, a warning is logged to the console.
+     *
+     */
+    async findIssuerCertificate(certificate) {
+        const firstCertificate = coerceCertificateChain(certificate)[0];
+        const certInfo = exploreCertificate(firstCertificate);
+        if (isSelfSigned2(certInfo)) {
+            // the certificate is self signed so is it's own issuer.
+            return firstCertificate;
+        }
+        const wantedIssuerKey = certInfo.tbsCertificate.extensions?.authorityKeyIdentifier?.keyIdentifier;
+        if (!wantedIssuerKey) {
+            // Certificate has no extension 3 ! the certificate might have been generated by an old system
+            debugLog("Certificate has no extension 3");
+            return null;
+        }
+        const issuerCertificates = [...this.#thumbs.issuers.certs.values()];
+        const selectedIssuerCertificates = findMatchingIssuerKey(issuerCertificates, wantedIssuerKey);
+        if (selectedIssuerCertificates.length > 0) {
+            if (selectedIssuerCertificates.length > 1) {
+                warningLog("Warning more than one issuer certificate exists with subjectKeyIdentifier ", wantedIssuerKey);
+            }
+            return selectedIssuerCertificates[0].certificate || null;
+        }
+        // check also in trusted  list
+        const trustedCertificates = [...this.#thumbs.trusted.values()];
+        const selectedTrustedCertificates = findMatchingIssuerKey(trustedCertificates, wantedIssuerKey);
+        if (selectedTrustedCertificates.length > 1) {
+            warningLog("Warning more than one certificate exists with subjectKeyIdentifier in trusted certificate list ", wantedIssuerKey, selectedTrustedCertificates.length);
+        }
+        return selectedTrustedCertificates.length > 0 ? selectedTrustedCertificates[0].certificate : null;
+    }
+    /**
+     * Outcome status for {@link CertificateManager.completeCertificateChain}.
+     */
+    static ChainCompletionStatus = ChainCompletionStatus;
+    /**
+     * Complete a certificate chain by walking the issuer store.
+     *
+     * Starting from the last certificate in the provided chain, this method
+     * repeatedly calls {@link findIssuerCertificate} to locate the parent
+     * certificate until it reaches a self-signed root or can no longer find
+     * an issuer.
+     *
+     * @param chain - the (potentially partial) certificate chain, leaf first
+     * @param maxDepth - maximum number of issuers to append (default: 10)
+     * @returns a {@link ChainCompletionResult} containing the (possibly completed)
+     *          chain, a status code, and an optional diagnostic message.
+     */
+    async completeCertificateChain(chain, maxDepth = 10) {
+        if (chain.length === 0) {
+            return {
+                chain,
+                status: ChainCompletionStatus.EmptyChain,
+                message: "Input chain is empty — nothing to complete."
+            };
+        }
+        // Re-scan the issuers folder to ensure we have the latest
+        await this.#scanCertFolder(this.issuersCertFolder, this.#thumbs.issuers.certs);
+        const result = [...chain];
+        let depth = 0;
+        while (depth < maxDepth) {
+            const lastCert = result[result.length - 1];
+            const lastInfo = exploreCertificate(lastCert);
+            // Stop if the last certificate is self-signed (root)
+            if (isSelfSigned2(lastInfo)) {
+                const wasExtended = result.length > chain.length;
+                return {
+                    chain: result,
+                    status: wasExtended ? ChainCompletionStatus.ChainCompleted : ChainCompletionStatus.AlreadyComplete,
+                    message: wasExtended
+                        ? `Chain completed: ${result.length - chain.length} issuer(s) appended, ending at self-signed root "${lastInfo.tbsCertificate.subject.commonName}".`
+                        : `Chain is already complete (self-signed root "${lastInfo.tbsCertificate.subject.commonName}").`
+                };
+            }
+            const issuerCert = await this.findIssuerCertificate(lastCert);
+            if (!issuerCert) {
+                // Cannot find the issuer — chain remains partial
+                const cn = lastInfo.tbsCertificate.subject.commonName ?? "?";
+                const akid = lastInfo.tbsCertificate.extensions?.authorityKeyIdentifier?.keyIdentifier ?? "?";
+                const msg = `Cannot find issuer for "${cn}" ` +
+                    `(authorityKeyIdentifier: ${akid}). ` +
+                    `Ensure the CA certificate is present in the issuers/certs folder.`;
+                warningLog(`completeCertificateChain: ${msg}`);
+                return {
+                    chain: result,
+                    status: ChainCompletionStatus.IssuerNotFound,
+                    message: msg
+                };
+            }
+            // Avoid loops: don't add the certificate if it's already in the chain
+            const issuerFingerprint = makeFingerprint(issuerCert);
+            const alreadyInChain = result.some((c) => makeFingerprint(c) === issuerFingerprint);
+            if (alreadyInChain) {
+                return {
+                    chain: result,
+                    status: ChainCompletionStatus.AlreadyComplete,
+                    message: `Chain ends at root "${exploreCertificate(issuerCert).tbsCertificate.subject.commonName}" (already present in chain).`
+                };
+            }
+            result.push(issuerCert);
+            depth++;
+        }
+        // maxDepth exceeded
+        return {
+            chain: result,
+            status: ChainCompletionStatus.MaxDepthReached,
+            message: `Chain completion stopped after ${maxDepth} iterations — possible circular chain or very deep hierarchy.`
+        };
+    }
+    /**
+     *
+     * check if the certificate explicitly appear in the trust list, the reject list or none.
+     * In case of being in the reject and trusted list at the same time is consider: rejected.
+     * @internal
+     * @private
+     */
+    async #checkRejectedOrTrusted(certificate) {
+        const firstCertificate = coerceCertificateChain(certificate)[0];
+        const fingerprint = makeFingerprint(firstCertificate);
+        debugLog("#checkRejectedOrTrusted fingerprint ", short(fingerprint));
+        await this.#readCertificates();
+        if (this.#thumbs.rejected.has(fingerprint)) {
+            return "rejected";
+        }
+        if (this.#thumbs.trusted.has(fingerprint)) {
+            return "trusted";
+        }
+        return "unknown";
+    }
+    async #moveCertificate(certificateOrChain, newStatus) {
+        await this.withLock2(async () => {
+            const chain = coerceCertificateChain(certificateOrChain);
+            const certificate = chain[0]; // leaf — used for indexing
+            const fingerprint = makeFingerprint(certificate);
+            let status = await this.#checkRejectedOrTrusted(certificate);
+            if (status === "unknown") {
+                // # unknown means rejected — write full chain to disk
+                const pem = toPem(chain, "CERTIFICATE");
+                const filename = safeStoreJoin(this.rejectedFolder, `${buildIdealCertificateName(certificate)}.pem`);
+                await fs.promises.writeFile(filename, pem);
+                this.#thumbs.rejected.set(fingerprint, { certificate, filename });
+                status = "rejected";
+            }
+            debugLog("#moveCertificate", fingerprint.substring(0, 10), "from", status, "to", newStatus);
+            if (status !== "rejected" && status !== "trusted") {
+                throw new Error(`#moveCertificate: unexpected status '${status}' for certificate ${fingerprint.substring(0, 10)}`);
+            }
+            if (status !== newStatus) {
+                const indexSrc = status === "rejected" ? this.#thumbs.rejected : this.#thumbs.trusted;
+                const srcEntry = indexSrc.get(fingerprint);
+                if (!srcEntry) {
+                    debugLog(" cannot find certificate ", fingerprint.substring(0, 10), " in", status);
+                    throw new Error(`#moveCertificate: certificate ${fingerprint.substring(0, 10)} not found in ${status} index`);
+                }
+                const destFolder = newStatus === "trusted" ? this.trustedFolder : this.rejectedFolder;
+                const certificateDest = safeStoreJoin(destFolder, path.basename(srcEntry.filename));
+                debugLog("#moveCertificate", fingerprint.substring(0, 10), "old name", srcEntry.filename);
+                debugLog("#moveCertificate", fingerprint.substring(0, 10), "new name", certificateDest);
+                await fs.promises.rename(srcEntry.filename, certificateDest);
+                indexSrc.delete(fingerprint);
+                const indexDest = newStatus === "trusted" ? this.#thumbs.trusted : this.#thumbs.rejected;
+                indexDest.set(fingerprint, { certificate, filename: certificateDest });
+            }
+        });
+    }
+    #findAssociatedCRLs(issuerCertificate) {
+        const issuerCertificateInfo = exploreCertificate(issuerCertificate);
+        const key = issuerCertificateInfo.tbsCertificate.subjectFingerPrint;
+        return this.#thumbs.issuersCrl.get(key) ?? this.#thumbs.crl.get(key) ?? null;
+    }
+    /**
+     * Check whether a certificate has been revoked by its issuer's CRL.
+     *
+     * - Self-signed certificates are never considered revoked.
+     * - If no `issuerCertificate` is provided, the method attempts
+     *   to find it via {@link findIssuerCertificate}.
+     *
+     * @param certificate - the DER-encoded certificate to check
+     * @param issuerCertificate - optional issuer certificate; looked
+     *   up automatically when omitted
+     * @returns `Good` if not revoked, `BadCertificateRevoked` if the
+     *   serial number appears in a CRL,
+     *   `BadCertificateRevocationUnknown` if no CRL is available,
+     *   or `BadCertificateChainIncomplete` if the issuer cannot be
+     *   found.
+     */
+    async isCertificateRevoked(certificate, issuerCertificate) {
+        const chain = coerceCertificateChain(certificate);
+        const firstCertificate = chain[0];
+        if (isSelfSigned3(firstCertificate)) {
+            return VerificationStatus.Good;
+        }
+        if (!issuerCertificate) {
+            issuerCertificate = await this.findIssuerCertificate(firstCertificate);
+        }
+        if (!issuerCertificate) {
+            issuerCertificate = findIssuerCertificateInChain(firstCertificate, chain);
+        }
+        if (!issuerCertificate) {
+            return VerificationStatus.BadCertificateChainIncomplete;
+        }
+        const crls = this.#findAssociatedCRLs(issuerCertificate);
+        if (!crls) {
+            return VerificationStatus.BadCertificateRevocationUnknown;
+        }
+        const certInfo = exploreCertificate(firstCertificate);
+        const serialNumber = certInfo.tbsCertificate.serialNumber || certInfo.tbsCertificate.extensions?.authorityKeyIdentifier?.serial || "";
+        const key = certInfo.tbsCertificate.extensions?.authorityKeyIdentifier?.authorityCertIssuerFingerPrint || "<unknown>";
+        const crl2 = this.#thumbs.crl.get(key) ?? null;
+        if (crls.serialNumbers[serialNumber] || crl2?.serialNumbers[serialNumber]) {
+            return VerificationStatus.BadCertificateRevoked;
+        }
+        return VerificationStatus.Good;
+    }
+    #pendingCrlToProcess = 0;
+    #onCrlProcessWaiters = [];
+    #queue = [];
+    #onCrlFileAdded(index, filename) {
+        this.#queue.push({ index, filename });
+        this.#pendingCrlToProcess += 1;
+        if (this.#pendingCrlToProcess === 1) {
+            this.#processNextCrl();
+        }
+    }
+    async #processNextCrl() {
+        try {
+            const nextCRL = this.#queue.shift();
+            if (!nextCRL)
+                return;
+            const { index, filename } = nextCRL;
+            const crl = await readCertificateRevocationList(filename);
+            const crlInfo = exploreCertificateRevocationList(crl);
+            debugLog(chalk.cyan("add CRL in folder "), filename);
+            const fingerprint = crlInfo.tbsCertList.issuerFingerprint;
+            if (!index.has(fingerprint)) {
+                index.set(fingerprint, { crls: [], serialNumbers: {} });
+            }
+            const data = index.get(fingerprint) || { crls: [], serialNumbers: {} };
+            data.crls.push({ crlInfo, filename });
+            // now inject serial numbers
+            for (const revokedCertificate of crlInfo.tbsCertList.revokedCertificates) {
+                const serialNumber = revokedCertificate.userCertificate;
+                if (!data.serialNumbers[serialNumber]) {
+                    data.serialNumbers[serialNumber] = revokedCertificate.revocationDate;
+                }
+            }
+            debugLog(chalk.cyan("CRL"), fingerprint, "serial numbers = ", Object.keys(data.serialNumbers));
+        }
+        catch (err) {
+            debugLog("CRL filename error =");
+            debugLog(err);
+        }
+        this.#pendingCrlToProcess -= 1;
+        if (this.#pendingCrlToProcess === 0) {
+            for (const waiter of this.#onCrlProcessWaiters) {
+                waiter();
+            }
+            this.#onCrlProcessWaiters.length = 0;
+        }
+        else {
+            this.#processNextCrl();
+        }
+    }
+    async #readCertificates() {
+        if (this.#readCertificatesCalled) {
+            return;
+        }
+        this.#readCertificatesCalled = true;
+        // Chokidar configuration choices:
+        //
+        // usePolling: false (default)
+        //   Use native OS file-system events (inotify on Linux,
+        //   FSEvents on macOS, ReadDirectoryChangesW on Windows)
+        //   for near-real-time detection of cert/CRL additions
+        //   and removals. This is significantly faster than
+        //   polling (milliseconds vs seconds).
+        //
+        //   Set OPCUA_PKI_USE_POLLING=true to revert to polling
+        //   for environments where native events are unreliable
+        //   (NFS, CIFS, Docker volumes, or other remote/virtual
+        //   file systems).
+        //
+        // persistent: false
+        //   Watchers do NOT keep the Node.js event loop alive.
+        //   This prevents the process from hanging if the
+        //   CertificateManager is not properly disposed. The
+        //   trade-off is that watchers stop receiving events if
+        //   there are no other active handles — acceptable since
+        //   CertificateManager always runs alongside a server.
+        //
+        // awaitWriteFinish: not set
+        //   Certificate and CRL files are small (typically < 5 KB)
+        //   and written atomically (fs.writeFile). No need to
+        //   wait for write stabilization, which would add a 2s+
+        //   delay before the in-memory index is updated.
+        //
+        const usePolling = process.env.OPCUA_PKI_USE_POLLING === "true";
+        const envInterval = process.env.OPCUA_PKI_POLLING_INTERVAL
+            ? parseInt(process.env.OPCUA_PKI_POLLING_INTERVAL, 10)
+            : undefined;
+        const pollingInterval = Math.min(10 * 60 * 1000, Math.max(100, envInterval ?? this.folderPollingInterval));
+        // depth: 0
+        //   PKI store folders are flat — certificates and CRLs sit
+        //   directly in them. Without an explicit depth chokidar
+        //   recurses without bound (handler.js: `oDepth == null`)
+        //   and descends into any subdirectory that appears, which
+        //   routes through NodeFsHandler._handleRead ->
+        //   FSWatcher._throttle. That schedules *ref'd* 1s timers;
+        //   a directory churning under the watcher can spin
+        //   thousands of them and keep the event loop alive
+        //   indefinitely, so an undisposed CertificateManager stops
+        //   the process from exiting. Note this is a timer problem,
+        //   not a handle problem: the fs.watch handles themselves
+        //   come back correctly unref'd. Flat watching keeps
+        //   _handleRead off subdirectories entirely.
+        //
+        const chokidarOptions = {
+            usePolling,
+            ...(usePolling ? { interval: pollingInterval } : {}),
+            depth: 0,
+            persistent: false
+        };
+        // Workaround for two problems with persistent:false:
+        //
+        //   1. Chokidar does forward persistent:false into fs.watch
+        //      (handler.js, createFsWatchInstance) and on current
+        //      Node the resulting handles do come back unref'd —
+        //      but that was not enough in practice on Windows when
+        //      0fbe111 was written, where undisposed instances
+        //      pinned the loop open. The explicit .unref() is kept
+        //      as the guarantee rather than trusting the platform.
+        //
+        //   2. Chokidar does not register an 'error' handler on
+        //      fs.watch when persistent:false (handler.js l.160-168).
+        //      On Windows + Node < 22, the native handle fires EPERM
+        //      when the watched directory is removed, which becomes
+        //      an uncaught exception that crashes the process.
+        //
+        // We install a single shared fs.watch() interception BEFORE
+        // creating all 5 watchers.  Every captured handle gets both
+        // an error handler (fix #2) and is later .unref()'d (fix #1).
+        //
+        // The interception stays active until ALL watchers have
+        // emitted "ready" — chokidar creates fs.watch handles
+        // asynchronously during directory scanning, so we must keep
+        // the interception alive until that completes.
+        const allCapturedHandles = [];
+        const origWatch = fs.watch;
+        let watcherReadyCount = 0;
+        const totalWatchers = 5;
+        fs.watch = ((...args) => {
+            const handle = origWatch.apply(fs, args);
+            handle.setMaxListeners(handle.getMaxListeners() + 1);
+            handle.on("error", () => {
+                /* swallow – watched directory was removed */
+            });
+            allCapturedHandles.push(handle);
+            return handle;
+        });
+        const createUnreffedWatcher = (folder) => {
+            const startIdx = allCapturedHandles.length;
+            const w = chokidar.watch(folder, chokidarOptions);
+            const unreffAll = () => {
+                // Unref only handles created for THIS watcher
+                for (let i = startIdx; i < allCapturedHandles.length; i++) {
+                    allCapturedHandles[i].unref();
+                }
+                // Restore fs.watch once ALL watchers are ready
+                watcherReadyCount++;
+                if (watcherReadyCount >= totalWatchers) {
+                    fs.watch = origWatch;
+                }
+            };
+            return { w, capturedHandles: allCapturedHandles.slice(startIdx), unreffAll };
+        };
+        // ── Phase 1: Async scan ─────────────────────────────────
+        // Populate the in-memory indexes by reading existing
+        // files. Uses async readdir/stat to yield the event loop
+        // between files. All 5 folders are scanned in parallel.
+        await Promise.all([
+            this.#scanCertFolder(this.trustedFolder, this.#thumbs.trusted),
+            this.#scanCertFolder(this.issuersCertFolder, this.#thumbs.issuers.certs),
+            this.#scanCertFolder(this.rejectedFolder, this.#thumbs.rejected),
+            this.#scanCrlFolder(this.crlFolder, this.#thumbs.crl),
+            this.#scanCrlFolder(this.issuersCrlFolder, this.#thumbs.issuersCrl)
+        ]);
+        // ── Phase 2: Deferred file watchers ─────────────────────
+        // Start chokidar watchers in the background. We do NOT
+        // await "ready" so initialize() returns immediately after
+        // the sync scan. Chokidar will re-discover existing files
+        // (harmless Map overwrites) then watch for live changes.
+        //
+        // When disableFileWatchers is set, skip the watcher setup
+        // entirely. The in-memory indexes are already populated
+        // from the scan above. Also restore fs.watch immediately
+        // since no watchers will be created.
+        if (this.#disableFileWatchers) {
+            fs.watch = origWatch;
+        }
+        else {
+            this.#startWatcher(this.trustedFolder, this.#thumbs.trusted, createUnreffedWatcher, "trusted");
+            this.#startWatcher(this.issuersCertFolder, this.#thumbs.issuers.certs, createUnreffedWatcher, "issuersCerts");
+            this.#startWatcher(this.rejectedFolder, this.#thumbs.rejected, createUnreffedWatcher, "rejected");
+            this.#startCrlWatcher(this.crlFolder, this.#thumbs.crl, createUnreffedWatcher, "crl");
+            this.#startCrlWatcher(this.issuersCrlFolder, this.#thumbs.issuersCrl, createUnreffedWatcher, "issuersCrl");
+        }
+    }
+    /**
+     * Scan a certificate folder and populate the in-memory index.
+     * Uses async readdir/stat to yield the event loop between
+     * file reads, preventing main-loop stalls with large folders.
+     */
+    async #scanCertFolder(folder, index) {
+        if (!fs.existsSync(folder))
+            return;
+        const files = await fs.promises.readdir(folder);
+        for (const file of files) {
+            const filename = path.join(folder, file);
+            try {
+                const stat = await fs.promises.stat(filename);
+                if (!stat.isFile())
+                    continue;
+                const certs = await readCertificateChainAsync(filename);
+                if (certs.length === 0)
+                    continue;
+                const certificate = certs[0];
+                // Legacy migration: if the file contained multiple
+                // certs (e.g. from old buggy toPem that wrapped a
+                // concatenated DER in a single PEM block), re-write
+                // with proper multi-block PEM and auto-register any
+                // intermediate CA certs in the issuers store.
+                // Best-effort: if the filesystem is read-only the
+                // migration is skipped — the leaf is still indexed.
+                if (certs.length > 1) {
+                    try {
+                        await fs.promises.writeFile(filename, toPem(certs, "CERTIFICATE"), "ascii");
+                    }
+                    catch (writeErr) {
+                        debugLog(`scanCertFolder: could not rewrite legacy PEM ${filename} (read-only fs?)`, writeErr);
+                    }
+                    for (let i = 1; i < certs.length; i++) {
+                        if (isIssuer(certs[i])) {
+                            try {
+                                await this.addIssuer(certs[i]);
+                            }
+                            catch (issuerErr) {
+                                debugLog(`scanCertFolder: could not auto-register issuer from ${filename}`, issuerErr);
+                            }
+                        }
+                    }
+                }
+                const info = exploreCertificate(certificate);
+                const fingerprint = makeFingerprint(certificate);
+                index.set(fingerprint, { certificate, filename, info });
+                this.#filenameToHash.set(filename, fingerprint);
+            }
+            catch (err) {
+                debugLog(`scanCertFolder: skipping ${filename}`, err);
+            }
+        }
+    }
+    /**
+     * Scan a CRL folder and populate the in-memory CRL index.
+     */
+    async #scanCrlFolder(folder, index) {
+        if (!fs.existsSync(folder))
+            return;
+        const files = await fs.promises.readdir(folder);
+        for (const file of files) {
+            const filename = path.join(folder, file);
+            try {
+                const stat = await fs.promises.stat(filename);
+                if (!stat.isFile())
+                    continue;
+                this.#onCrlFileAdded(index, filename);
+            }
+            catch (err) {
+                debugLog(`scanCrlFolder: skipping ${filename}`, err);
+            }
+        }
+        await this.#waitAndCheckCRLProcessingStatus();
+    }
+    /**
+     * Start a chokidar watcher for a CRL folder.
+     * Non-blocking — does NOT await "ready".
+     */
+    #startCrlWatcher(folder, index, createUnreffedWatcher, store) {
+        const { w, unreffAll } = createUnreffedWatcher(folder);
+        w.on("error", (err) => {
+            debugLog(`chokidar CRL watcher error on ${folder}:`, err);
+        });
+        let ready = false;
+        w.on("unlink", (filename) => {
+            for (const [key, data] of index.entries()) {
+                data.crls = data.crls.filter((c) => c.filename !== filename);
+                if (data.crls.length === 0) {
+                    index.delete(key);
+                }
+            }
+            if (ready) {
+                this.emit("crlRemoved", { store, filename });
+            }
+        });
+        w.on("add", (filename) => {
+            if (ready) {
+                this.#onCrlFileAdded(index, filename);
+                this.emit("crlAdded", { store, filename });
+            }
+        });
+        w.on("change", (changedPath) => {
+            debugLog("change in folder ", folder, changedPath);
+        });
+        this.#watchers.push(w);
+        this.#pendingUnrefs.add(unreffAll);
+        w.on("ready", () => {
+            ready = true;
+            this.#pendingUnrefs.delete(unreffAll);
+            unreffAll();
+        });
+    }
+    /**
+     * Start a chokidar watcher for a certificate folder.
+     * Non-blocking — does NOT await "ready".
+     */
+    #startWatcher(folder, index, createUnreffedWatcher, store) {
+        const { w, unreffAll } = createUnreffedWatcher(folder);
+        w.on("error", (err) => {
+            debugLog(`chokidar cert watcher error on ${folder}:`, err);
+        });
+        let ready = false;
+        w.on("unlink", (filename) => {
+            debugLog(chalk.cyan(`unlink in folder ${folder}`), filename);
+            const h = this.#filenameToHash.get(filename);
+            if (h && index.has(h)) {
+                index.delete(h);
+                this.emit("certificateRemoved", { store, fingerprint: h, filename });
+            }
+        });
+        w.on("add", (filename) => {
+            debugLog(chalk.cyan(`add in folder ${folder}`), filename);
+            try {
+                const certificate = readCertificateChain(filename)[0];
+                const info = exploreCertificate(certificate);
+                const fingerprint = makeFingerprint(certificate);
+                const isNew = !index.has(fingerprint);
+                index.set(fingerprint, { certificate, filename, info });
+                this.#filenameToHash.set(filename, fingerprint);
+                debugLog(chalk.magenta("CERT"), info.tbsCertificate.subjectFingerPrint, info.tbsCertificate.serialNumber, info.tbsCertificate.extensions?.authorityKeyIdentifier?.authorityCertIssuerFingerPrint);
+                if (ready || isNew) {
+                    this.emit("certificateAdded", { store, certificate, fingerprint, filename });
+                }
+            }
+            catch (err) {
+                debugLog(`Walk files in folder ${folder} with file ${filename}`);
+                debugLog(err);
+            }
+        });
+        w.on("change", (changedPath) => {
+            debugLog(chalk.cyan(`change in folder ${folder}`), changedPath);
+            try {
+                const certificate = readCertificateChain(changedPath)[0];
+                const newFingerprint = makeFingerprint(certificate);
+                const oldHash = this.#filenameToHash.get(changedPath);
+                if (oldHash && oldHash !== newFingerprint) {
+                    index.delete(oldHash);
+                }
+                index.set(newFingerprint, { certificate, filename: changedPath, info: exploreCertificate(certificate) });
+                this.#filenameToHash.set(changedPath, newFingerprint);
+                this.emit("certificateChange", { store, certificate, fingerprint: newFingerprint, filename: changedPath });
+            }
+            catch (err) {
+                debugLog(`change event: failed to re-read ${changedPath}`, err);
+            }
+        });
+        this.#watchers.push(w);
+        this.#pendingUnrefs.add(unreffAll);
+        w.on("ready", () => {
+            ready = true;
+            this.#pendingUnrefs.delete(unreffAll);
+            unreffAll();
+            debugLog("ready");
+            debugLog([...index.keys()].map((k) => k.substring(0, 10)));
+        });
+    }
+    // make sure that all crls have been processed.
+    async #waitAndCheckCRLProcessingStatus() {
+        return new Promise((resolve, _reject) => {
+            if (this.#pendingCrlToProcess === 0) {
+                setImmediate(resolve);
+                return;
+            }
+            this.#onCrlProcessWaiters.push(resolve);
+        });
+    }
+}
+//# sourceMappingURL=certificate_manager.js.map