node-opcua-pki 6.21.0 → 6.22.1

package/dist/core.mjs

@@ -7,7 +7,7 @@ import {
   defaultSubject,
   escapeOpensslConfDoubleQuoted,
   renderCaConfig
-} from "./chunk-2HTNH73K.mjs";
+} from "./chunk-EQ4DGI4M.mjs";
 export {
   CaDatabase,
   CertificateAuthorityCore,

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { PrivateKey, Certificate, SubjectOptions, DER, CertificateRevocationList } from 'node-opcua-crypto';
-export { PrivateKeyPassphraseRequiredError, Subject, SubjectOptions } from 'node-opcua-crypto';
-import { C as CaBackend, a as CertificateAuthorityCore, P as Params, b as ProcessAltNamesParam, c as CertificateAuthorityCoreOptions, K as KeySize, d as PrivateKeyPassphrase, e as PrivateKeyProvider, f as CreateSelfSignCertificateParam, F as Filename } from './core-C6faZClF.mjs';
-export { g as CertificateStatus, h as CreateCertificateSigningRequestOptions, i as CreateCertificateSigningRequestWithConfigOptions, j as CreateSelfSignCertificateWithConfigParam, G as GenerateKeyPairAndSignOptions, k as GenerateKeyPairAndSignPFXOptions, I as InitializeCSRResult, l as InstallCACertificateResult, m as KeyLength, N as NativeCaBackend, n as PkiBackendCapabilities, S as SignCertificateOptions, o as StartDateEndDateParam, T as Thumbprint, p as adjustApplicationUri, q as adjustDate, r as quote, s as resolvePrivateKeyPassphrase } from './core-C6faZClF.mjs';
+import { IKeyOperations, PrivateKey, Certificate, SubjectOptions, DER, CertificateRevocationList } from 'node-opcua-crypto';
+export { AsymmetricDecryptParams, AsymmetricSignParams, IKeyOperations, KeyMetadata, PrivateKeyPassphraseRequiredError, PrivateKeyUnavailableError, Subject, SubjectOptions } from 'node-opcua-crypto';
+import { C as CaBackend, a as CertificateAuthorityCore, P as Params, b as ProcessAltNamesParam, c as CertificateAuthorityCoreOptions, K as KeySize, d as PrivateKeyPassphrase, e as PrivateKeyProvider, f as CreateSelfSignCertificateParam, F as Filename } from './core-BwqSJPHc.mjs';
+export { g as CertificateStatus, h as CreateCertificateSigningRequestOptions, i as CreateCertificateSigningRequestWithConfigOptions, j as CreateSelfSignCertificateWithConfigParam, G as GenerateKeyPairAndSignOptions, k as GenerateKeyPairAndSignPFXOptions, I as InitializeCSRResult, l as InstallCACertificateResult, m as KeyLength, N as NativeCaBackend, n as PkiBackendCapabilities, S as SignCertificateOptions, o as StartDateEndDateParam, T as Thumbprint, p as adjustApplicationUri, q as adjustDate, r as isOpaqueSigner, s as quote, t as resolvePrivateKeyPassphrase } from './core-BwqSJPHc.mjs';
 import { EventEmitter } from 'node:events';
 
 /**
@@ -239,6 +239,29 @@ interface CertificateManagerOptions {
      * ignored.
      */
     privateKeyProvider?: PrivateKeyProvider;
+    /**
+     * Use a private key this manager can never read: an opaque
+     * {@link IKeyOperations} provider (HSM, KMS, TPM, OS keystore, ...).
+     *
+     * The distinction with `privateKeyProvider` matters: a
+     * `privateKeyProvider` *sources raw key material* from elsewhere and
+     * hands it back; `keyOperations` never reveals the key — only sign and
+     * decrypt operations on it. Prefer `keyOperations` whenever the key
+     * does not need to be exportable.
+     *
+     * When set:
+     * - {@link CertificateManager.getPrivateKey} and
+     *   {@link CertificateManager.reencryptPrivateKey} throw
+     *   `PrivateKeyUnavailableError` — there is no key material to return
+     *   or rewrite, and no on-disk key is generated or expected;
+     * - {@link CertificateManager.getKeyOperations} returns this object;
+     * - `initialize()` fails closed if the provider cannot answer
+     *   `getKeyMetadata()` (unreachable HSM, misconfiguration);
+     * - mutually exclusive with `privateKeyProvider` and
+     *   `privateKeyPassphrase` — both describe key *material*, which an
+     *   opaque configuration does not have.
+     */
+    keyOperations?: IKeyOperations;
 }
 /**
  * Parameters for {@link createSelfSignedCertificate}.
@@ -341,6 +364,8 @@ declare enum VerificationStatus {
 }
 declare function coerceCertificateChain(certificate: Certificate | Certificate[]): Certificate[];
 declare function makeFingerprint(certificate: Certificate | Certificate[] | CertificateRevocationList): string;
+declare function toFilenameLabel(commonName: string): string;
+declare function safeStoreJoin(folder: string, filename: string): string;
 /**
  * Check if the provided certificate acts as an issuer (CA)
  * @param certificate - the DER-encoded certificate
@@ -533,6 +558,27 @@ declare class CertificateManager extends EventEmitter {
      * authority on what the current key is.
      */
     getPrivateKey(): Promise<PrivateKey>;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): IKeyOperations;
     /**
      * Enable, disable, or rotate the passphrase protecting the on-disk
      * private key: decrypt with `oldPassphrase` (omit if the key is
@@ -954,4 +1000,4 @@ declare function convertPFXtoPEM(pfxFile: Filename, pemFile: Filename, passphras
  */
 declare function dumpPFX(pfxFile: Filename, passphrase?: string): Promise<string>;
 
-export { type AddCertificateValidationOptions, CaBackend, CertificateAuthority, CertificateAuthorityCore, CertificateAuthorityCoreOptions, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStore, type ChainCompletionResult, ChainCompletionStatus, type CreatePFXOptions, CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, Filename, KeySize, OpenSslCaBackend, Params, PrivateKeyPassphrase, PrivateKeyProvider, ProcessAltNamesParam, VerificationStatus, type VerifyCertificateOptions, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint };
+export { type AddCertificateValidationOptions, CaBackend, CertificateAuthority, CertificateAuthorityCore, CertificateAuthorityCoreOptions, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStore, type ChainCompletionResult, ChainCompletionStatus, type CreatePFXOptions, CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, Filename, KeySize, OpenSslCaBackend, Params, PrivateKeyPassphrase, PrivateKeyProvider, ProcessAltNamesParam, VerificationStatus, type VerifyCertificateOptions, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint, safeStoreJoin, toFilenameLabel };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { PrivateKey, Certificate, SubjectOptions, DER, CertificateRevocationList } from 'node-opcua-crypto';
-export { PrivateKeyPassphraseRequiredError, Subject, SubjectOptions } from 'node-opcua-crypto';
-import { C as CaBackend, a as CertificateAuthorityCore, P as Params, b as ProcessAltNamesParam, c as CertificateAuthorityCoreOptions, K as KeySize, d as PrivateKeyPassphrase, e as PrivateKeyProvider, f as CreateSelfSignCertificateParam, F as Filename } from './core-C6faZClF.js';
-export { g as CertificateStatus, h as CreateCertificateSigningRequestOptions, i as CreateCertificateSigningRequestWithConfigOptions, j as CreateSelfSignCertificateWithConfigParam, G as GenerateKeyPairAndSignOptions, k as GenerateKeyPairAndSignPFXOptions, I as InitializeCSRResult, l as InstallCACertificateResult, m as KeyLength, N as NativeCaBackend, n as PkiBackendCapabilities, S as SignCertificateOptions, o as StartDateEndDateParam, T as Thumbprint, p as adjustApplicationUri, q as adjustDate, r as quote, s as resolvePrivateKeyPassphrase } from './core-C6faZClF.js';
+import { IKeyOperations, PrivateKey, Certificate, SubjectOptions, DER, CertificateRevocationList } from 'node-opcua-crypto';
+export { AsymmetricDecryptParams, AsymmetricSignParams, IKeyOperations, KeyMetadata, PrivateKeyPassphraseRequiredError, PrivateKeyUnavailableError, Subject, SubjectOptions } from 'node-opcua-crypto';
+import { C as CaBackend, a as CertificateAuthorityCore, P as Params, b as ProcessAltNamesParam, c as CertificateAuthorityCoreOptions, K as KeySize, d as PrivateKeyPassphrase, e as PrivateKeyProvider, f as CreateSelfSignCertificateParam, F as Filename } from './core-BwqSJPHc.js';
+export { g as CertificateStatus, h as CreateCertificateSigningRequestOptions, i as CreateCertificateSigningRequestWithConfigOptions, j as CreateSelfSignCertificateWithConfigParam, G as GenerateKeyPairAndSignOptions, k as GenerateKeyPairAndSignPFXOptions, I as InitializeCSRResult, l as InstallCACertificateResult, m as KeyLength, N as NativeCaBackend, n as PkiBackendCapabilities, S as SignCertificateOptions, o as StartDateEndDateParam, T as Thumbprint, p as adjustApplicationUri, q as adjustDate, r as isOpaqueSigner, s as quote, t as resolvePrivateKeyPassphrase } from './core-BwqSJPHc.js';
 import { EventEmitter } from 'node:events';
 
 /**
@@ -239,6 +239,29 @@ interface CertificateManagerOptions {
      * ignored.
      */
     privateKeyProvider?: PrivateKeyProvider;
+    /**
+     * Use a private key this manager can never read: an opaque
+     * {@link IKeyOperations} provider (HSM, KMS, TPM, OS keystore, ...).
+     *
+     * The distinction with `privateKeyProvider` matters: a
+     * `privateKeyProvider` *sources raw key material* from elsewhere and
+     * hands it back; `keyOperations` never reveals the key — only sign and
+     * decrypt operations on it. Prefer `keyOperations` whenever the key
+     * does not need to be exportable.
+     *
+     * When set:
+     * - {@link CertificateManager.getPrivateKey} and
+     *   {@link CertificateManager.reencryptPrivateKey} throw
+     *   `PrivateKeyUnavailableError` — there is no key material to return
+     *   or rewrite, and no on-disk key is generated or expected;
+     * - {@link CertificateManager.getKeyOperations} returns this object;
+     * - `initialize()` fails closed if the provider cannot answer
+     *   `getKeyMetadata()` (unreachable HSM, misconfiguration);
+     * - mutually exclusive with `privateKeyProvider` and
+     *   `privateKeyPassphrase` — both describe key *material*, which an
+     *   opaque configuration does not have.
+     */
+    keyOperations?: IKeyOperations;
 }
 /**
  * Parameters for {@link createSelfSignedCertificate}.
@@ -341,6 +364,8 @@ declare enum VerificationStatus {
 }
 declare function coerceCertificateChain(certificate: Certificate | Certificate[]): Certificate[];
 declare function makeFingerprint(certificate: Certificate | Certificate[] | CertificateRevocationList): string;
+declare function toFilenameLabel(commonName: string): string;
+declare function safeStoreJoin(folder: string, filename: string): string;
 /**
  * Check if the provided certificate acts as an issuer (CA)
  * @param certificate - the DER-encoded certificate
@@ -533,6 +558,27 @@ declare class CertificateManager extends EventEmitter {
      * authority on what the current key is.
      */
     getPrivateKey(): Promise<PrivateKey>;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): IKeyOperations;
     /**
      * Enable, disable, or rotate the passphrase protecting the on-disk
      * private key: decrypt with `oldPassphrase` (omit if the key is
@@ -954,4 +1000,4 @@ declare function convertPFXtoPEM(pfxFile: Filename, pemFile: Filename, passphras
  */
 declare function dumpPFX(pfxFile: Filename, passphrase?: string): Promise<string>;
 
-export { type AddCertificateValidationOptions, CaBackend, CertificateAuthority, CertificateAuthorityCore, CertificateAuthorityCoreOptions, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStore, type ChainCompletionResult, ChainCompletionStatus, type CreatePFXOptions, CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, Filename, KeySize, OpenSslCaBackend, Params, PrivateKeyPassphrase, PrivateKeyProvider, ProcessAltNamesParam, VerificationStatus, type VerifyCertificateOptions, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint };
+export { type AddCertificateValidationOptions, CaBackend, CertificateAuthority, CertificateAuthorityCore, CertificateAuthorityCoreOptions, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStore, type ChainCompletionResult, ChainCompletionStatus, type CreatePFXOptions, CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, Filename, KeySize, OpenSslCaBackend, Params, PrivateKeyPassphrase, PrivateKeyProvider, ProcessAltNamesParam, VerificationStatus, type VerifyCertificateOptions, coerceCertificateChain, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, isIntermediateIssuer, isIssuer, isRootIssuer, makeFingerprint, safeStoreJoin, toFilenameLabel };

package/dist/index.js

@@ -38,6 +38,7 @@ __export(lib_exports, {
   NativeCaBackend: () => NativeCaBackend,
   OpenSslCaBackend: () => OpenSslCaBackend,
   PrivateKeyPassphraseRequiredError: () => import_node_opcua_crypto10.PrivateKeyPassphraseRequiredError,
+  PrivateKeyUnavailableError: () => import_node_opcua_crypto10.PrivateKeyUnavailableError,
   Subject: () => import_node_opcua_crypto3.Subject,
   VerificationStatus: () => VerificationStatus,
   adjustApplicationUri: () => adjustApplicationUri,
@@ -54,10 +55,13 @@ __export(lib_exports, {
   install_prerequisite: () => install_prerequisite,
   isIntermediateIssuer: () => isIntermediateIssuer,
   isIssuer: () => isIssuer,
+  isOpaqueSigner: () => isOpaqueSigner,
   isRootIssuer: () => isRootIssuer,
   makeFingerprint: () => makeFingerprint,
   quote: () => quote,
-  resolvePrivateKeyPassphrase: () => resolvePrivateKeyPassphrase
+  resolvePrivateKeyPassphrase: () => resolvePrivateKeyPassphrase,
+  safeStoreJoin: () => safeStoreJoin,
+  toFilenameLabel: () => toFilenameLabel
 });
 module.exports = __toCommonJS(lib_exports);
 var import_node_opcua_crypto10 = require("node-opcua-crypto");
@@ -72,6 +76,9 @@ var import_node_assert = __toESM(require("assert"));
 function quote(str) {
   return `"${str || ""}"`;
 }
+function isOpaqueSigner(privateKey) {
+  return typeof privateKey !== "string" && typeof privateKey.sign === "function";
+}
 async function resolvePrivateKeyPassphrase(passphrase) {
   if (passphrase === void 0) {
     return void 0;
@@ -1060,8 +1067,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(import_chalk4.default.cyan("                  CWD         "), options.cwd);
@@ -2887,8 +2918,9 @@ async function createCertificateSigningRequestAsync(certificateSigningRequestFil
   (0, import_node_assert6.default)(typeof certificateSigningRequestFilename === "string");
   const subject = params.subject ? new import_node_opcua_crypto6.Subject(params.subject).toString() : void 0;
   displaySubtitle("- Creating a Certificate Signing Request with subtile");
-  const privateKeyPem = typeof params.privateKey === "string" ? await import_node_fs9.default.promises.readFile(params.privateKey, "utf-8") : (0, import_node_opcua_crypto6.coercePrivateKeyPem)(params.privateKey);
-  const privateKey = await (0, import_node_opcua_crypto6.pemToPrivateKey)(privateKeyPem);
+  const privateKey = isOpaqueSigner(params.privateKey) ? params.privateKey : await (0, import_node_opcua_crypto6.pemToPrivateKey)(
+    typeof params.privateKey === "string" ? await import_node_fs9.default.promises.readFile(params.privateKey, "utf-8") : (0, import_node_opcua_crypto6.coercePrivateKeyPem)(params.privateKey)
+  );
   const { csr } = await (0, import_node_opcua_crypto6.createCertificateSigningRequest)({
     privateKey,
     dns: params.dns,
@@ -2898,7 +2930,9 @@ async function createCertificateSigningRequestAsync(certificateSigningRequestFil
     purpose: params.purpose
   });
   await import_node_fs9.default.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}`);
 }
 
@@ -2925,8 +2959,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 import_node_fs10.default.promises.readFile(params.privateKey, "utf-8") : (0, import_node_opcua_crypto7.coercePrivateKeyPem)(params.privateKey);
-  const privateKey = await (0, import_node_opcua_crypto7.pemToPrivateKey)(privateKeyPem);
+  const privateKey = isOpaqueSigner(params.privateKey) ? params.privateKey : await (0, import_node_opcua_crypto7.pemToPrivateKey)(
+    typeof params.privateKey === "string" ? await import_node_fs10.default.promises.readFile(params.privateKey, "utf-8") : (0, import_node_opcua_crypto7.coercePrivateKeyPem)(params.privateKey)
+  );
   const { cert } = await (0, import_node_opcua_crypto7.createSelfSignedCertificate)({
     privateKey,
     notBefore: params.startDate,
@@ -2992,18 +3027,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 = (0, import_node_opcua_crypto8.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 = import_node_path8.default.resolve(folder, filename);
+  const base = import_node_path8.default.resolve(folder);
+  if (full !== base && !full.startsWith(base + import_node_path8.default.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);
@@ -3231,6 +3279,9 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
   #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
@@ -3274,6 +3325,17 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
     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 (!import_node_fs11.default.existsSync(this.#location)) {
       throw new Error(`CertificateManager cannot access location ${this.#location}`);
@@ -3315,6 +3377,11 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
    * authority on what the current key is.
    */
   async getPrivateKey() {
+    if (this.#keyOperations) {
+      throw new import_node_opcua_crypto8.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();
     }
@@ -3340,6 +3407,75 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
   }
   /** 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: (0, import_node_opcua_crypto8.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 (0, import_node_opcua_crypto8.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
@@ -3361,6 +3497,11 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
    * disk file for this method to rewrite).
    */
   async reencryptPrivateKey(oldPassphrase, newPassphrase) {
+    if (this.#keyOperations) {
+      throw new import_node_opcua_crypto8.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");
     }
@@ -3486,7 +3627,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
         } catch (_err) {
           return "BadCertificateInvalid";
         }
-        const filename = import_node_path8.default.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, (0, import_node_opcua_crypto8.toPem)(chain, "CERTIFICATE"));
         this.#thumbs.rejected.set(fingerprint, { certificate: leafCertificate, filename });
@@ -3709,7 +3850,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
     mkdirRecursiveSync(import_node_path8.default.join(pkiDir, "issuers"));
     mkdirRecursiveSync(import_node_path8.default.join(pkiDir, "issuers/certs"));
     mkdirRecursiveSync(import_node_path8.default.join(pkiDir, "issuers/crl"));
-    const ownsDiskKey = !this.#privateKeyProvider;
+    const ownsDiskKey = !this.#privateKeyProvider && !this.#keyOperations;
     const needsKeyGeneration = ownsDiskKey && !import_node_fs11.default.existsSync(this.privateKey);
     const needsKeyEncryption = ownsDiskKey && !needsKeyGeneration && this.#privateKeyPassphrase !== void 0 && !isEncryptedPrivateKeyFile(this.privateKey);
     if (!import_node_fs11.default.existsSync(this.configFile) || needsKeyGeneration || needsKeyEncryption) {
@@ -3735,14 +3876,14 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
         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();
     }
   }
@@ -3827,7 +3968,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
     if (typeof params.applicationUri !== "string") {
       throw new Error("createSelfSignedCertificate: expecting applicationUri to be a string");
     }
-    if (!this.#privateKeyProvider && !import_node_fs11.default.existsSync(this.privateKey)) {
+    if (!this.#privateKeyProvider && !this.#keyOperations && !import_node_fs11.default.existsSync(this.privateKey)) {
       throw new Error(`Cannot find private key ${this.privateKey}`);
     }
     let certificateFilename = import_node_path8.default.join(this.rootDir, "own/certs/self_signed_certificate.pem");
@@ -3836,7 +3977,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
       ...params,
       rootDir: this.rootDir,
       configFile: this.configFile,
-      privateKey: await this.getPrivateKey(),
+      privateKey: await this.#resolveSigningKey(),
       subject: params.subject || "CN=FIXME"
     };
     await this.withLock2(async () => {
@@ -3864,7 +4005,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
       ...params,
       rootDir: import_node_path8.default.resolve(this.rootDir),
       configFile: import_node_path8.default.resolve(this.configFile),
-      privateKey: await this.getPrivateKey()
+      privateKey: await this.#resolveSigningKey()
     };
     return await this.withLock2(async () => {
       const now = /* @__PURE__ */ new Date();
@@ -3894,7 +4035,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
     if (this.#thumbs.issuers.certs.has(fingerprint)) {
       return "Good" /* Good */;
     }
-    const filename = import_node_path8.default.join(this.issuersCertFolder, `issuer_${buildIdealCertificateName(certificate)}.pem`);
+    const filename = safeStoreJoin(this.issuersCertFolder, `issuer_${buildIdealCertificateName(certificate)}.pem`);
     await import_node_fs11.default.promises.writeFile(filename, pemCertificate, "ascii");
     this.#thumbs.issuers.certs.set(fingerprint, { certificate, filename });
     if (addInTrustList) {
@@ -4353,7 +4494,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
       let status = await this.#checkRejectedOrTrusted(certificate);
       if (status === "unknown") {
         const pem = (0, import_node_opcua_crypto8.toPem)(chain, "CERTIFICATE");
-        const filename = import_node_path8.default.join(this.rejectedFolder, `${buildIdealCertificateName(certificate)}.pem`);
+        const filename = safeStoreJoin(this.rejectedFolder, `${buildIdealCertificateName(certificate)}.pem`);
         await import_node_fs11.default.promises.writeFile(filename, pem);
         this.#thumbs.rejected.set(fingerprint, { certificate, filename });
         status = "rejected";
@@ -4370,7 +4511,7 @@ var CertificateManager = class _CertificateManager extends import_node_events.Ev
           throw new Error(`#moveCertificate: certificate ${fingerprint.substring(0, 10)} not found in ${status} index`);
         }
         const destFolder = newStatus === "trusted" ? this.trustedFolder : this.rejectedFolder;
-        const certificateDest = import_node_path8.default.join(destFolder, import_node_path8.default.basename(srcEntry.filename));
+        const certificateDest = safeStoreJoin(destFolder, import_node_path8.default.basename(srcEntry.filename));
         debugLog("#moveCertificate", fingerprint.substring(0, 10), "old name", srcEntry.filename);
         debugLog("#moveCertificate", fingerprint.substring(0, 10), "new name", certificateDest);
         await import_node_fs11.default.promises.rename(srcEntry.filename, certificateDest);
@@ -4840,6 +4981,7 @@ async function dumpPFX(pfxFile, passphrase = "") {
   NativeCaBackend,
   OpenSslCaBackend,
   PrivateKeyPassphraseRequiredError,
+  PrivateKeyUnavailableError,
   Subject,
   VerificationStatus,
   adjustApplicationUri,
@@ -4856,9 +4998,12 @@ async function dumpPFX(pfxFile, passphrase = "") {
   install_prerequisite,
   isIntermediateIssuer,
   isIssuer,
+  isOpaqueSigner,
   isRootIssuer,
   makeFingerprint,
   quote,
-  resolvePrivateKeyPassphrase
+  resolvePrivateKeyPassphrase,
+  safeStoreJoin,
+  toFilenameLabel
 });
 //# sourceMappingURL=index.js.map