node-opcua-pki 6.21.0 → 6.22.0

package/dist/bin/pki.mjs

@@ -93,6 +93,9 @@ var init_hostname = __esm({
 
 // packages/node-opcua-pki/lib/toolbox/common.ts
 import assert2 from "assert";
+function isOpaqueSigner(privateKey) {
+  return typeof privateKey !== "string" && typeof privateKey.sign === "function";
+}
 async function resolvePrivateKeyPassphrase(passphrase) {
   if (passphrase === void 0) {
     return void 0;
@@ -276,8 +279,9 @@ async function createCertificateSigningRequestAsync(certificateSigningRequestFil
   assert4(typeof certificateSigningRequestFilename === "string");
   const subject = params.subject ? new Subject(params.subject).toString() : void 0;
   displaySubtitle("- Creating a Certificate Signing Request with subtile");
-  const privateKeyPem = typeof params.privateKey === "string" ? await fs2.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 fs2.promises.readFile(params.privateKey, "utf-8") : coercePrivateKeyPem(params.privateKey)
+  );
   const { csr } = await createCertificateSigningRequest({
     privateKey,
     dns: params.dns,
@@ -287,13 +291,16 @@ async function createCertificateSigningRequestAsync(certificateSigningRequestFil
     purpose: params.purpose
   });
   await fs2.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}`);
 }
 var init_create_certificate_signing_request = __esm({
   "packages/node-opcua-pki/lib/toolbox/without_openssl/create_certificate_signing_request.ts"() {
     "use strict";
     init_esm_shims();
+    init_common();
     init_display();
   }
 });
@@ -327,8 +334,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 fs3.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 fs3.promises.readFile(params.privateKey, "utf-8") : coercePrivateKeyPem2(params.privateKey)
+  );
   const { cert } = await createSelfSignedCertificate1({
     privateKey,
     notBefore: params.startDate,
@@ -383,11 +391,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,
@@ -640,6 +651,9 @@ var init_certificate_manager = __esm({
       #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
@@ -683,6 +697,17 @@ var init_certificate_manager = __esm({
         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 (!fs4.existsSync(this.#location)) {
           throw new Error(`CertificateManager cannot access location ${this.#location}`);
@@ -724,6 +749,11 @@ var init_certificate_manager = __esm({
        * 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();
         }
@@ -749,6 +779,75 @@ var init_certificate_manager = __esm({
       }
       /** 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
@@ -770,6 +869,11 @@ var init_certificate_manager = __esm({
        * 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");
         }
@@ -1118,7 +1222,7 @@ var init_certificate_manager = __esm({
         mkdirRecursiveSync(path2.join(pkiDir, "issuers"));
         mkdirRecursiveSync(path2.join(pkiDir, "issuers/certs"));
         mkdirRecursiveSync(path2.join(pkiDir, "issuers/crl"));
-        const ownsDiskKey = !this.#privateKeyProvider;
+        const ownsDiskKey = !this.#privateKeyProvider && !this.#keyOperations;
         const needsKeyGeneration = ownsDiskKey && !fs4.existsSync(this.privateKey);
         const needsKeyEncryption = ownsDiskKey && !needsKeyGeneration && this.#privateKeyPassphrase !== void 0 && !isEncryptedPrivateKeyFile(this.privateKey);
         if (!fs4.existsSync(this.configFile) || needsKeyGeneration || needsKeyEncryption) {
@@ -1144,14 +1248,14 @@ var init_certificate_manager = __esm({
             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();
         }
       }
@@ -1236,7 +1340,7 @@ var init_certificate_manager = __esm({
         if (typeof params.applicationUri !== "string") {
           throw new Error("createSelfSignedCertificate: expecting applicationUri to be a string");
         }
-        if (!this.#privateKeyProvider && !fs4.existsSync(this.privateKey)) {
+        if (!this.#privateKeyProvider && !this.#keyOperations && !fs4.existsSync(this.privateKey)) {
           throw new Error(`Cannot find private key ${this.privateKey}`);
         }
         let certificateFilename = path2.join(this.rootDir, "own/certs/self_signed_certificate.pem");
@@ -1245,7 +1349,7 @@ var init_certificate_manager = __esm({
           ...params,
           rootDir: this.rootDir,
           configFile: this.configFile,
-          privateKey: await this.getPrivateKey(),
+          privateKey: await this.#resolveSigningKey(),
           subject: params.subject || "CN=FIXME"
         };
         await this.withLock2(async () => {
@@ -1273,7 +1377,7 @@ var init_certificate_manager = __esm({
           ...params,
           rootDir: path2.resolve(this.rootDir),
           configFile: path2.resolve(this.configFile),
-          privateKey: await this.getPrivateKey()
+          privateKey: await this.#resolveSigningKey()
         };
         return await this.withLock2(async () => {
           const now = /* @__PURE__ */ new Date();