node-opcua-pki 6.12.2 → 6.13.0

package/dist/index.d.mts

@@ -671,6 +671,20 @@ interface CertificateManagerOptions {
      * Defaults are secure — all checks enabled.
      */
     addCertificateValidationOptions?: AddCertificateValidationOptions;
+    /**
+     * When `true`, the CertificateManager will **not** start
+     * chokidar file-system watchers on the PKI folders.
+     *
+     * The initial file-system scan still runs so the in-memory
+     * indexes are populated, but live change detection is
+     * disabled.  This is useful in test / CI environments where
+     * many CertificateManager instances are created in parallel
+     * and the accumulated `fs.watch` handles exhaust the libuv
+     * thread-pool, causing event-loop starvation.
+     *
+     * @defaultValue false
+     */
+    disableFileWatchers?: boolean;
 }
 /**
  * Parameters for {@link createSelfSignedCertificate}.
@@ -857,6 +871,33 @@ declare enum CertificateManagerState {
  * await cm.dispose();
  * ```
  */
+/**
+ * Status codes returned by {@link CertificateManager.completeCertificateChain}.
+ */
+declare enum ChainCompletionStatus {
+    /** The chain already reached a self-signed root — no action was needed. */
+    AlreadyComplete = "AlreadyComplete",
+    /** One or more issuer certificates were successfully appended. */
+    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. */
+    IssuerNotFound = "IssuerNotFound",
+    /** The input chain was empty. */
+    EmptyChain = "EmptyChain",
+    /** Chain completion was stopped because the maximum depth was reached. */
+    MaxDepthReached = "MaxDepthReached"
+}
+/**
+ * Result of {@link CertificateManager.completeCertificateChain}.
+ */
+interface ChainCompletionResult {
+    /** The (possibly completed) certificate chain, leaf first. */
+    chain: Certificate[];
+    /** Status code indicating whether completion succeeded and why/why not. */
+    status: ChainCompletionStatus;
+    /** Human-readable diagnostic message. */
+    message: string;
+}
 declare class CertificateManager extends EventEmitter {
     #private;
     /**
@@ -1150,6 +1191,24 @@ declare class CertificateManager extends EventEmitter {
      *
      */
     findIssuerCertificate(certificate: Certificate | Certificate[]): Promise<Certificate | null>;
+    /**
+     * Outcome status for {@link CertificateManager.completeCertificateChain}.
+     */
+    static readonly ChainCompletionStatus: typeof 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.
+     */
+    completeCertificateChain(chain: Certificate[], maxDepth?: number): Promise<ChainCompletionResult>;
     /**
      * Check whether a certificate has been revoked by its issuer's CRL.
      *
@@ -1305,4 +1364,4 @@ declare function dumpPFX(pfxFile: Filename, passphrase?: string): Promise<string
  */
 declare function install_prerequisite(): Promise<string>;
 
-export { type AddCertificateValidationOptions, CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type GenerateKeyPairAndSignOptions, type GenerateKeyPairAndSignPFXOptions, type InitializeCSRResult, type InstallCACertificateResult, type KeyLength, type KeySize, type Params, type ProcessAltNamesParam, type SignCertificateOptions, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint, quote };
+export { type AddCertificateValidationOptions, CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type ChainCompletionResult, ChainCompletionStatus, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type GenerateKeyPairAndSignOptions, type GenerateKeyPairAndSignPFXOptions, type InitializeCSRResult, type InstallCACertificateResult, type KeyLength, type KeySize, type Params, type ProcessAltNamesParam, type SignCertificateOptions, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint, quote };

package/dist/index.d.ts

@@ -671,6 +671,20 @@ interface CertificateManagerOptions {
      * Defaults are secure — all checks enabled.
      */
     addCertificateValidationOptions?: AddCertificateValidationOptions;
+    /**
+     * When `true`, the CertificateManager will **not** start
+     * chokidar file-system watchers on the PKI folders.
+     *
+     * The initial file-system scan still runs so the in-memory
+     * indexes are populated, but live change detection is
+     * disabled.  This is useful in test / CI environments where
+     * many CertificateManager instances are created in parallel
+     * and the accumulated `fs.watch` handles exhaust the libuv
+     * thread-pool, causing event-loop starvation.
+     *
+     * @defaultValue false
+     */
+    disableFileWatchers?: boolean;
 }
 /**
  * Parameters for {@link createSelfSignedCertificate}.
@@ -857,6 +871,33 @@ declare enum CertificateManagerState {
  * await cm.dispose();
  * ```
  */
+/**
+ * Status codes returned by {@link CertificateManager.completeCertificateChain}.
+ */
+declare enum ChainCompletionStatus {
+    /** The chain already reached a self-signed root — no action was needed. */
+    AlreadyComplete = "AlreadyComplete",
+    /** One or more issuer certificates were successfully appended. */
+    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. */
+    IssuerNotFound = "IssuerNotFound",
+    /** The input chain was empty. */
+    EmptyChain = "EmptyChain",
+    /** Chain completion was stopped because the maximum depth was reached. */
+    MaxDepthReached = "MaxDepthReached"
+}
+/**
+ * Result of {@link CertificateManager.completeCertificateChain}.
+ */
+interface ChainCompletionResult {
+    /** The (possibly completed) certificate chain, leaf first. */
+    chain: Certificate[];
+    /** Status code indicating whether completion succeeded and why/why not. */
+    status: ChainCompletionStatus;
+    /** Human-readable diagnostic message. */
+    message: string;
+}
 declare class CertificateManager extends EventEmitter {
     #private;
     /**
@@ -1150,6 +1191,24 @@ declare class CertificateManager extends EventEmitter {
      *
      */
     findIssuerCertificate(certificate: Certificate | Certificate[]): Promise<Certificate | null>;
+    /**
+     * Outcome status for {@link CertificateManager.completeCertificateChain}.
+     */
+    static readonly ChainCompletionStatus: typeof 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.
+     */
+    completeCertificateChain(chain: Certificate[], maxDepth?: number): Promise<ChainCompletionResult>;
     /**
      * Check whether a certificate has been revoked by its issuer's CRL.
      *
@@ -1305,4 +1364,4 @@ declare function dumpPFX(pfxFile: Filename, passphrase?: string): Promise<string
  */
 declare function install_prerequisite(): Promise<string>;
 
-export { type AddCertificateValidationOptions, CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type GenerateKeyPairAndSignOptions, type GenerateKeyPairAndSignPFXOptions, type InitializeCSRResult, type InstallCACertificateResult, type KeyLength, type KeySize, type Params, type ProcessAltNamesParam, type SignCertificateOptions, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint, quote };
+export { type AddCertificateValidationOptions, CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type ChainCompletionResult, ChainCompletionStatus, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type GenerateKeyPairAndSignOptions, type GenerateKeyPairAndSignPFXOptions, type InitializeCSRResult, type InstallCACertificateResult, type KeyLength, type KeySize, type Params, type ProcessAltNamesParam, type SignCertificateOptions, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint, quote };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(lib_exports, {
   CertificateAuthority: () => CertificateAuthority,
   CertificateManager: () => CertificateManager,
   CertificateManagerState: () => CertificateManagerState,
+  ChainCompletionStatus: () => ChainCompletionStatus,
   Subject: () => import_node_opcua_crypto.Subject,
   VerificationStatus: () => VerificationStatus,
   adjustApplicationUri: () => adjustApplicationUri,
@@ -2050,6 +2051,14 @@ var CertificateManagerState = /* @__PURE__ */ ((CertificateManagerState2) => {
   CertificateManagerState2[CertificateManagerState2["Disposed"] = 4] = "Disposed";
   return CertificateManagerState2;
 })(CertificateManagerState || {});
+var ChainCompletionStatus = /* @__PURE__ */ ((ChainCompletionStatus2) => {
+  ChainCompletionStatus2["AlreadyComplete"] = "AlreadyComplete";
+  ChainCompletionStatus2["ChainCompleted"] = "ChainCompleted";
+  ChainCompletionStatus2["IssuerNotFound"] = "IssuerNotFound";
+  ChainCompletionStatus2["EmptyChain"] = "EmptyChain";
+  ChainCompletionStatus2["MaxDepthReached"] = "MaxDepthReached";
+  return ChainCompletionStatus2;
+})(ChainCompletionStatus || {});
 var CertificateManager = class _CertificateManager extends import_node_events.EventEmitter {
   // ── Global instance registry ─────────────────────────────────
   // Tracks all initialized CertificateManager instances so their
@@ -2142,6 +2151,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
   #filenameToHash = /* @__PURE__ */ new Map();
   #initializingPromise;
   #addCertValidation;
+  #disableFileWatchers;
   #thumbs = {
     rejected: /* @__PURE__ */ new Map(),
     trusted: /* @__PURE__ */ new Map(),
@@ -2175,6 +2185,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
       ignoreMissingRevocationList: v.ignoreMissingRevocationList ?? false,
       maxChainLength: v.maxChainLength ?? 5
     };
+    this.#disableFileWatchers = options.disableFileWatchers ?? process.env.OPCUA_PKI_DISABLE_FILE_WATCHERS === "true";
     mkdirRecursiveSync(options.location);
     if (!import_node_fs10.default.existsSync(this.#location)) {
       throw new Error(`CertificateManager cannot access location ${this.#location}`);
@@ -3039,6 +3050,75 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
     }
     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: "EmptyChain" /* EmptyChain */,
+        message: "Input chain is empty \u2014 nothing to complete."
+      };
+    }
+    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 = (0, import_node_opcua_crypto5.exploreCertificate)(lastCert);
+      if (isSelfSigned2(lastInfo)) {
+        const wasExtended = result.length > chain.length;
+        return {
+          chain: result,
+          status: wasExtended ? "ChainCompleted" /* ChainCompleted */ : "AlreadyComplete" /* 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) {
+        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: "IssuerNotFound" /* IssuerNotFound */,
+          message: msg
+        };
+      }
+      const issuerFingerprint = makeFingerprint(issuerCert);
+      const alreadyInChain = result.some((c) => makeFingerprint(c) === issuerFingerprint);
+      if (alreadyInChain) {
+        return {
+          chain: result,
+          status: "AlreadyComplete" /* AlreadyComplete */,
+          message: `Chain ends at root "${(0, import_node_opcua_crypto5.exploreCertificate)(issuerCert).tbsCertificate.subject.commonName}" (already present in chain).`
+        };
+      }
+      result.push(issuerCert);
+      depth++;
+    }
+    return {
+      chain: result,
+      status: "MaxDepthReached" /* MaxDepthReached */,
+      message: `Chain completion stopped after ${maxDepth} iterations \u2014 possible circular chain or very deep hierarchy.`
+    };
+  }
   /**
    *
    * check if the certificate explicitly appear in the trust list, the reject list or none.
@@ -3234,11 +3314,15 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
       this.#scanCrlFolder(this.crlFolder, this.#thumbs.crl),
       this.#scanCrlFolder(this.issuersCrlFolder, this.#thumbs.issuersCrl)
     ]);
-    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");
+    if (this.#disableFileWatchers) {
+      import_node_fs10.default.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.
@@ -3420,6 +3504,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
   CertificateAuthority,
   CertificateManager,
   CertificateManagerState,
+  ChainCompletionStatus,
   Subject,
   VerificationStatus,
   adjustApplicationUri,