node-opcua-pki 6.21.0 → 6.22.0

package/dist/index.mjs

@@ -13,16 +13,20 @@ import {
   ensurePrivateDirectory,
   g_config,
   isEncryptedPrivateKeyFile,
+  isOpaqueSigner,
   makePath,
   mkdirRecursiveSync,
   quote,
   resolvePrivateKeyPassphrase,
   restrictPrivateFilePermissions,
   warningLog
-} from "./chunk-2HTNH73K.mjs";
+} from "./chunk-EQ4DGI4M.mjs";
 
 // packages/node-opcua-pki/lib/index.ts
-import { PrivateKeyPassphraseRequiredError } from "node-opcua-crypto";
+import {
+  PrivateKeyPassphraseRequiredError,
+  PrivateKeyUnavailableError as PrivateKeyUnavailableError2
+} from "node-opcua-crypto";
 
 // packages/node-opcua-pki/lib/ca/backends/openssl_ca_backend.ts
 import fs4 from "fs";
@@ -975,11 +979,14 @@ import { drainPendingLocks, withLock } from "@ster5/global-mutex";
 import chalk3 from "chalk";
 import chokidar from "chokidar";
 import {
+  caSignerFromKeyOperations,
   exploreCertificate,
   exploreCertificateInfo,
   exploreCertificateRevocationList,
   generatePrivateKeyFile,
+  keyOperationsFromPrivateKey,
   makeSHA1Thumbprint,
+  PrivateKeyUnavailableError,
   readCertificateChain,
   readCertificateChainAsync,
   readCertificateRevocationList,
@@ -1006,8 +1013,9 @@ async function createCertificateSigningRequestAsync(certificateSigningRequestFil
   assert3(typeof certificateSigningRequestFilename === "string");
   const subject = params.subject ? new Subject3(params.subject).toString() : void 0;
   displaySubtitle("- Creating a Certificate Signing Request with subtile");
-  const privateKeyPem = typeof params.privateKey === "string" ? await fs5.promises.readFile(params.privateKey, "utf-8") : coercePrivateKeyPem(params.privateKey);
-  const privateKey = await pemToPrivateKey(privateKeyPem);
+  const privateKey = isOpaqueSigner(params.privateKey) ? params.privateKey : await pemToPrivateKey(
+    typeof params.privateKey === "string" ? await fs5.promises.readFile(params.privateKey, "utf-8") : coercePrivateKeyPem(params.privateKey)
+  );
   const { csr } = await createCertificateSigningRequest({
     privateKey,
     dns: params.dns,
@@ -1017,7 +1025,9 @@ async function createCertificateSigningRequestAsync(certificateSigningRequestFil
     purpose: params.purpose
   });
   await fs5.promises.writeFile(certificateSigningRequestFilename, csr, "utf-8");
-  display(`- privateKey ${typeof params.privateKey === "string" ? params.privateKey : "<in-memory>"}`);
+  display(
+    `- privateKey ${typeof params.privateKey === "string" ? params.privateKey : isOpaqueSigner(params.privateKey) ? "<opaque-signer>" : "<in-memory>"}`
+  );
   display(`- certificateSigningRequestFilename ${certificateSigningRequestFilename}`);
 }
 
@@ -1050,8 +1060,9 @@ async function createSelfSignedCertificateAsync(certificate, params) {
   subject = subject.toString();
   const purpose = params.purpose;
   displayTitle("Generate a certificate request");
-  const privateKeyPem = typeof params.privateKey === "string" ? await fs6.promises.readFile(params.privateKey, "utf-8") : coercePrivateKeyPem2(params.privateKey);
-  const privateKey = await pemToPrivateKey2(privateKeyPem);
+  const privateKey = isOpaqueSigner(params.privateKey) ? params.privateKey : await pemToPrivateKey2(
+    typeof params.privateKey === "string" ? await fs6.promises.readFile(params.privateKey, "utf-8") : coercePrivateKeyPem2(params.privateKey)
+  );
   const { cert } = await createSelfSignedCertificate1({
     privateKey,
     notBefore: params.startDate,
@@ -1356,6 +1367,9 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
   #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
@@ -1399,6 +1413,17 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
     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 (!fs7.existsSync(this.#location)) {
       throw new Error(`CertificateManager cannot access location ${this.#location}`);
@@ -1440,6 +1465,11 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
    * 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 \u2014 use getKeyOperations() instead"
+      );
+    }
     if (this.#privateKeyProvider) {
       return await this.#privateKeyProvider.getPrivateKey();
     }
@@ -1465,6 +1495,75 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
   }
   /** 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();
+        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
@@ -1486,6 +1585,11 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
    * disk file for this method to rewrite).
    */
   async reencryptPrivateKey(oldPassphrase, newPassphrase) {
+    if (this.#keyOperations) {
+      throw new PrivateKeyUnavailableError(
+        "reencryptPrivateKey: not supported when keyOperations is configured \u2014 there is no key material to rewrite"
+      );
+    }
     if (this.#privateKeyProvider) {
       throw new Error("reencryptPrivateKey: not supported when a privateKeyProvider is configured");
     }
@@ -1834,7 +1938,7 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
     mkdirRecursiveSync(path4.join(pkiDir, "issuers"));
     mkdirRecursiveSync(path4.join(pkiDir, "issuers/certs"));
     mkdirRecursiveSync(path4.join(pkiDir, "issuers/crl"));
-    const ownsDiskKey = !this.#privateKeyProvider;
+    const ownsDiskKey = !this.#privateKeyProvider && !this.#keyOperations;
     const needsKeyGeneration = ownsDiskKey && !fs7.existsSync(this.privateKey);
     const needsKeyEncryption = ownsDiskKey && !needsKeyGeneration && this.#privateKeyPassphrase !== void 0 && !isEncryptedPrivateKeyFile(this.privateKey);
     if (!fs7.existsSync(this.configFile) || needsKeyGeneration || needsKeyEncryption) {
@@ -1860,14 +1964,14 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
         if (ownsDiskKey) {
           restrictPrivateFilePermissions(this.privateKey, 384);
         }
-        await this.getPrivateKey();
+        await this.#probePrivateKey();
         await this.#readCertificates();
       });
     } else {
       if (ownsDiskKey) {
         restrictPrivateFilePermissions(this.privateKey, 384);
       }
-      await this.getPrivateKey();
+      await this.#probePrivateKey();
       await this.#readCertificates();
     }
   }
@@ -1952,7 +2056,7 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
     if (typeof params.applicationUri !== "string") {
       throw new Error("createSelfSignedCertificate: expecting applicationUri to be a string");
     }
-    if (!this.#privateKeyProvider && !fs7.existsSync(this.privateKey)) {
+    if (!this.#privateKeyProvider && !this.#keyOperations && !fs7.existsSync(this.privateKey)) {
       throw new Error(`Cannot find private key ${this.privateKey}`);
     }
     let certificateFilename = path4.join(this.rootDir, "own/certs/self_signed_certificate.pem");
@@ -1961,7 +2065,7 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
       ...params,
       rootDir: this.rootDir,
       configFile: this.configFile,
-      privateKey: await this.getPrivateKey(),
+      privateKey: await this.#resolveSigningKey(),
       subject: params.subject || "CN=FIXME"
     };
     await this.withLock2(async () => {
@@ -1989,7 +2093,7 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
       ...params,
       rootDir: path4.resolve(this.rootDir),
       configFile: path4.resolve(this.configFile),
-      privateKey: await this.getPrivateKey()
+      privateKey: await this.#resolveSigningKey()
     };
     return await this.withLock2(async () => {
       const now = /* @__PURE__ */ new Date();
@@ -2976,6 +3080,7 @@ export {
   NativeCaBackend,
   OpenSslCaBackend,
   PrivateKeyPassphraseRequiredError,
+  PrivateKeyUnavailableError2 as PrivateKeyUnavailableError,
   Subject,
   VerificationStatus,
   adjustApplicationUri,
@@ -2992,6 +3097,7 @@ export {
   install_prerequisite,
   isIntermediateIssuer,
   isIssuer,
+  isOpaqueSigner,
   isRootIssuer,
   makeFingerprint,
   quote,