node-opcua-pki 6.21.0 → 6.22.1

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";
@@ -407,8 +411,32 @@ function passinArg(passphrase = "") {
 function renderForDisplay(file, args) {
   return [file, ...args].map((a) => a === "" || /[\s"'`$\\]/.test(a) ? JSON.stringify(a) : a).join(" ");
 }
+function hasUnsafeArgChar(value) {
+  for (const ch of value) {
+    const code = ch.codePointAt(0);
+    if (code < 32 || code === 127) {
+      return true;
+    }
+    if (code < 128) {
+      continue;
+    }
+    if (/[\p{L}\p{N}\p{M}]/u.test(ch)) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+function checkArgs(file, args) {
+  for (const value of [file, ...args]) {
+    if (typeof value === "string" && hasUnsafeArgChar(value)) {
+      throw new Error(`execute_openssl: refusing argument with an unexpected character: ${JSON.stringify(value)}`);
+    }
+  }
+}
 async function execute2(file, args, options) {
   const from = new Error();
+  checkArgs(file, args);
   options.cwd = options.cwd || process.cwd();
   if (!g_config.silent) {
     warningLog(chalk2.cyan("                  CWD         "), options.cwd);
@@ -975,11 +1003,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 +1037,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 +1049,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 +1084,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,
@@ -1117,18 +1152,31 @@ function makeFingerprint(certificate) {
 function short(stringToShorten) {
   return stringToShorten.substring(0, 10);
 }
-var forbiddenChars = /[\x00-\x1F<>:"/\\|?*]/g;
+var disallowedInLabel = /[^A-Za-z0-9._ -]/g;
+function toFilenameLabel(commonName) {
+  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 = commonName.replace(forbiddenChars, "_");
+    const sanitizedCommonName = toFilenameLabel(commonName);
     return `${sanitizedCommonName}[${fingerprint}]`;
   } catch (_err) {
     return `invalid_certificate_[${fingerprint}]`;
   }
 }
+function safeStoreJoin(folder, filename) {
+  const full = path4.resolve(folder, filename);
+  const base = path4.resolve(folder);
+  if (full !== base && !full.startsWith(base + path4.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);
@@ -1356,6 +1404,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 +1450,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 +1502,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 +1532,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 +1622,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");
     }
@@ -1611,7 +1752,7 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
         } catch (_err) {
           return "BadCertificateInvalid";
         }
-        const filename = path4.join(this.rejectedFolder, `${buildIdealCertificateName(leafCertificate)}.pem`);
+        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 });
@@ -1834,7 +1975,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 +2001,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 +2093,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 +2102,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 +2130,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();
@@ -2019,7 +2160,7 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
     if (this.#thumbs.issuers.certs.has(fingerprint)) {
       return "Good" /* Good */;
     }
-    const filename = path4.join(this.issuersCertFolder, `issuer_${buildIdealCertificateName(certificate)}.pem`);
+    const filename = safeStoreJoin(this.issuersCertFolder, `issuer_${buildIdealCertificateName(certificate)}.pem`);
     await fs7.promises.writeFile(filename, pemCertificate, "ascii");
     this.#thumbs.issuers.certs.set(fingerprint, { certificate, filename });
     if (addInTrustList) {
@@ -2478,7 +2619,7 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
       let status = await this.#checkRejectedOrTrusted(certificate);
       if (status === "unknown") {
         const pem = toPem(chain, "CERTIFICATE");
-        const filename = path4.join(this.rejectedFolder, `${buildIdealCertificateName(certificate)}.pem`);
+        const filename = safeStoreJoin(this.rejectedFolder, `${buildIdealCertificateName(certificate)}.pem`);
         await fs7.promises.writeFile(filename, pem);
         this.#thumbs.rejected.set(fingerprint, { certificate, filename });
         status = "rejected";
@@ -2495,7 +2636,7 @@ var CertificateManager = class _CertificateManager extends EventEmitter {
           throw new Error(`#moveCertificate: certificate ${fingerprint.substring(0, 10)} not found in ${status} index`);
         }
         const destFolder = newStatus === "trusted" ? this.trustedFolder : this.rejectedFolder;
-        const certificateDest = path4.join(destFolder, path4.basename(srcEntry.filename));
+        const certificateDest = safeStoreJoin(destFolder, path4.basename(srcEntry.filename));
         debugLog("#moveCertificate", fingerprint.substring(0, 10), "old name", srcEntry.filename);
         debugLog("#moveCertificate", fingerprint.substring(0, 10), "new name", certificateDest);
         await fs7.promises.rename(srcEntry.filename, certificateDest);
@@ -2976,6 +3117,7 @@ export {
   NativeCaBackend,
   OpenSslCaBackend,
   PrivateKeyPassphraseRequiredError,
+  PrivateKeyUnavailableError2 as PrivateKeyUnavailableError,
   Subject,
   VerificationStatus,
   adjustApplicationUri,
@@ -2992,9 +3134,12 @@ export {
   install_prerequisite,
   isIntermediateIssuer,
   isIssuer,
+  isOpaqueSigner,
   isRootIssuer,
   makeFingerprint,
   quote,
-  resolvePrivateKeyPassphrase
+  resolvePrivateKeyPassphrase,
+  safeStoreJoin,
+  toFilenameLabel
 };
 //# sourceMappingURL=index.mjs.map