node-opcua-pki 6.15.0 → 6.16.0

package/dist/index.d.mts

@@ -59,6 +59,17 @@ interface StartDateEndDateParam {
     endDate?: Date;
     /** Number of days the certificate is valid. @defaultValue 365 */
     validity?: number;
+    /**
+     * Certificate validity in milliseconds.
+     *
+     * When provided, takes precedence over {@link validity} and enables
+     * sub-day validity (X.509 supports second precision per RFC 5280
+     * §4.1.2.5; OpenSSL is invoked with `-startdate`/`-enddate` already).
+     *
+     * Typical use is short-lived certificates for demos or for renewal
+     * cycle testing. Existing day-based callers are unaffected.
+     */
+    validityMs?: number;
 }
 /**
  * Parameters for creating a self-signed certificate.
@@ -240,6 +251,13 @@ interface IssuedCertificateRecord {
 interface SignCertificateOptions {
     /** Certificate validity in days (default: 365). */
     validity?: number;
+    /**
+     * Certificate validity in milliseconds.
+     *
+     * When provided, takes precedence over {@link validity} and enables
+     * sub-day validity (e.g. 10-minute certificates for renewal demos).
+     */
+    validityMs?: number;
     /** Override the certificate start date. */
     startDate?: Date;
     /** Override DNS SANs. */
@@ -251,6 +269,34 @@ interface SignCertificateOptions {
     /** Override the X.500 subject. */
     subject?: SubjectOptions | string;
 }
+/**
+ * Capabilities advertised by a PKI backend (or by this
+ * {@link CertificateAuthority}) so consumers can clamp requested
+ * validity to the limits the backend can actually honor.
+ *
+ * Useful for the GDS Pull / Push management flows, where the CA may
+ * be supplied by an external service (step-ca, EJBCA, …) with its
+ * own minimum / maximum / granularity constraints.
+ *
+ * @see CertificateAuthority.getCapabilities
+ */
+interface PkiBackendCapabilities {
+    /** Smallest validity this backend can issue, in milliseconds. */
+    minValidityMs: number;
+    /** Largest validity this backend will issue, in milliseconds. */
+    maxValidityMs: number;
+    /**
+     * Validity is rounded up to the nearest multiple of this many
+     * milliseconds. For `node-opcua-pki`'s OpenSSL-based CA this is
+     * 1 000 ms (one second — the X.509 floor per RFC 5280 §4.1.2.5).
+     */
+    validityGranularityMs: number;
+    /**
+     * Native unit the backend works in. Diagnostic only — callers
+     * always pass `validityMs` (US-208 / US-210).
+     */
+    nativeUnit: "second" | "minute" | "hour" | "day";
+}
 /**
  * Options for {@link CertificateAuthority.generateKeyPairAndSignDER}.
  */
@@ -265,6 +311,13 @@ interface GenerateKeyPairAndSignOptions {
     ip?: string[];
     /** Certificate validity in days (default: 365). */
     validity?: number;
+    /**
+     * Certificate validity in milliseconds.
+     *
+     * When provided, takes precedence over {@link validity} and enables
+     * sub-day validity (e.g. 10-minute certificates for renewal demos).
+     */
+    validityMs?: number;
     /** Certificate start date (default: now). */
     startDate?: Date;
     /** RSA key size in bits (default: 2048). */
@@ -475,6 +528,28 @@ declare class CertificateAuthority {
      * @returns the signed certificate as a DER-encoded buffer
      */
     signCertificateRequestFromDER(csrDer: Buffer, options?: SignCertificateOptions): Promise<Buffer>;
+    /**
+     * Advertise the validity limits this CA can honor.
+     *
+     * Consumers (notably the GDS server in [`cert_auth.ts`](https://github.com/sterfive/node-opcua-gds))
+     * clamp a requested validity against these bounds before calling
+     * {@link signCertificateRequestFromDER}, so a misconfigured
+     * `defaultCertValidity` cannot ask the CA for something it cannot
+     * produce.
+     *
+     * Defaults match the OpenSSL-backed implementation:
+     * - `minValidityMs = 60_000` (1 minute) — practical floor; the
+     *   X.509 spec floor is 1 second but very short certs are rarely
+     *   useful and pathological for any real deployment.
+     * - `maxValidityMs = 10 * 365 * 86_400_000` (≈ 10 years) — long
+     *   enough for root CAs.
+     * - `validityGranularityMs = 1_000` (1 second) — RFC 5280 §4.1.2.5
+     *   floor on `notBefore` / `notAfter`.
+     * - `nativeUnit = "second"` — what `x509Date()` actually encodes.
+     *
+     * @see US-208 — the consumer-side capability story.
+     */
+    getCapabilities(): PkiBackendCapabilities;
     /**
      * Generate a new RSA key pair, create an internal CSR, sign it
      * with this CA, and return both the certificate and private key
@@ -1440,4 +1515,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 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 };
+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 PkiBackendCapabilities, 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

@@ -59,6 +59,17 @@ interface StartDateEndDateParam {
     endDate?: Date;
     /** Number of days the certificate is valid. @defaultValue 365 */
     validity?: number;
+    /**
+     * Certificate validity in milliseconds.
+     *
+     * When provided, takes precedence over {@link validity} and enables
+     * sub-day validity (X.509 supports second precision per RFC 5280
+     * §4.1.2.5; OpenSSL is invoked with `-startdate`/`-enddate` already).
+     *
+     * Typical use is short-lived certificates for demos or for renewal
+     * cycle testing. Existing day-based callers are unaffected.
+     */
+    validityMs?: number;
 }
 /**
  * Parameters for creating a self-signed certificate.
@@ -240,6 +251,13 @@ interface IssuedCertificateRecord {
 interface SignCertificateOptions {
     /** Certificate validity in days (default: 365). */
     validity?: number;
+    /**
+     * Certificate validity in milliseconds.
+     *
+     * When provided, takes precedence over {@link validity} and enables
+     * sub-day validity (e.g. 10-minute certificates for renewal demos).
+     */
+    validityMs?: number;
     /** Override the certificate start date. */
     startDate?: Date;
     /** Override DNS SANs. */
@@ -251,6 +269,34 @@ interface SignCertificateOptions {
     /** Override the X.500 subject. */
     subject?: SubjectOptions | string;
 }
+/**
+ * Capabilities advertised by a PKI backend (or by this
+ * {@link CertificateAuthority}) so consumers can clamp requested
+ * validity to the limits the backend can actually honor.
+ *
+ * Useful for the GDS Pull / Push management flows, where the CA may
+ * be supplied by an external service (step-ca, EJBCA, …) with its
+ * own minimum / maximum / granularity constraints.
+ *
+ * @see CertificateAuthority.getCapabilities
+ */
+interface PkiBackendCapabilities {
+    /** Smallest validity this backend can issue, in milliseconds. */
+    minValidityMs: number;
+    /** Largest validity this backend will issue, in milliseconds. */
+    maxValidityMs: number;
+    /**
+     * Validity is rounded up to the nearest multiple of this many
+     * milliseconds. For `node-opcua-pki`'s OpenSSL-based CA this is
+     * 1 000 ms (one second — the X.509 floor per RFC 5280 §4.1.2.5).
+     */
+    validityGranularityMs: number;
+    /**
+     * Native unit the backend works in. Diagnostic only — callers
+     * always pass `validityMs` (US-208 / US-210).
+     */
+    nativeUnit: "second" | "minute" | "hour" | "day";
+}
 /**
  * Options for {@link CertificateAuthority.generateKeyPairAndSignDER}.
  */
@@ -265,6 +311,13 @@ interface GenerateKeyPairAndSignOptions {
     ip?: string[];
     /** Certificate validity in days (default: 365). */
     validity?: number;
+    /**
+     * Certificate validity in milliseconds.
+     *
+     * When provided, takes precedence over {@link validity} and enables
+     * sub-day validity (e.g. 10-minute certificates for renewal demos).
+     */
+    validityMs?: number;
     /** Certificate start date (default: now). */
     startDate?: Date;
     /** RSA key size in bits (default: 2048). */
@@ -475,6 +528,28 @@ declare class CertificateAuthority {
      * @returns the signed certificate as a DER-encoded buffer
      */
     signCertificateRequestFromDER(csrDer: Buffer, options?: SignCertificateOptions): Promise<Buffer>;
+    /**
+     * Advertise the validity limits this CA can honor.
+     *
+     * Consumers (notably the GDS server in [`cert_auth.ts`](https://github.com/sterfive/node-opcua-gds))
+     * clamp a requested validity against these bounds before calling
+     * {@link signCertificateRequestFromDER}, so a misconfigured
+     * `defaultCertValidity` cannot ask the CA for something it cannot
+     * produce.
+     *
+     * Defaults match the OpenSSL-backed implementation:
+     * - `minValidityMs = 60_000` (1 minute) — practical floor; the
+     *   X.509 spec floor is 1 second but very short certs are rarely
+     *   useful and pathological for any real deployment.
+     * - `maxValidityMs = 10 * 365 * 86_400_000` (≈ 10 years) — long
+     *   enough for root CAs.
+     * - `validityGranularityMs = 1_000` (1 second) — RFC 5280 §4.1.2.5
+     *   floor on `notBefore` / `notAfter`.
+     * - `nativeUnit = "second"` — what `x509Date()` actually encodes.
+     *
+     * @see US-208 — the consumer-side capability story.
+     */
+    getCapabilities(): PkiBackendCapabilities;
     /**
      * Generate a new RSA key pair, create an internal CSR, sign it
      * with this CA, and return both the certificate and private key
@@ -1440,4 +1515,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 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 };
+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 PkiBackendCapabilities, 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

@@ -77,9 +77,17 @@ function adjustDate(params) {
   (0, import_node_assert.default)(params instanceof Object);
   params.startDate = params.startDate || /* @__PURE__ */ new Date();
   (0, import_node_assert.default)(params.startDate instanceof Date);
-  params.validity = params.validity || 365;
-  params.endDate = new Date(params.startDate.getTime());
-  params.endDate.setDate(params.startDate.getDate() + params.validity);
+  if (params.validityMs !== void 0) {
+    if (params.validityMs <= 0) {
+      throw new RangeError(`validityMs must be > 0 (got ${params.validityMs})`);
+    }
+    params.endDate = new Date(params.startDate.getTime() + params.validityMs);
+    params.validity = Math.ceil(params.validityMs / 864e5);
+  } else {
+    params.validity = params.validity || 365;
+    params.endDate = new Date(params.startDate.getTime());
+    params.endDate.setDate(params.startDate.getDate() + params.validity);
+  }
   (0, import_node_assert.default)(params.endDate instanceof Date);
   (0, import_node_assert.default)(params.startDate instanceof Date);
 }
@@ -1400,14 +1408,15 @@ var CertificateAuthority = class {
    * @returns the signed certificate as a DER-encoded buffer
    */
   async signCertificateRequestFromDER(csrDer, options) {
-    const validity = options?.validity ?? 365;
     const tmpDir = await import_node_fs7.default.promises.mkdtemp(import_node_path5.default.join(import_node_os3.default.tmpdir(), "pki-sign-"));
     try {
       const csrFile = import_node_path5.default.join(tmpDir, "request.csr");
       const certFile = import_node_path5.default.join(tmpDir, "certificate.pem");
       const csrPem = (0, import_node_opcua_crypto2.toPem)(csrDer, "CERTIFICATE REQUEST");
       await import_node_fs7.default.promises.writeFile(csrFile, csrPem, "utf-8");
-      const signingParams = { validity };
+      const signingParams = {};
+      if (options?.validityMs !== void 0) signingParams.validityMs = options.validityMs;
+      else signingParams.validity = options?.validity ?? 365;
       if (options?.startDate) signingParams.startDate = options.startDate;
       if (options?.dns) signingParams.dns = options.dns;
       if (options?.ip) signingParams.ip = options.ip;
@@ -1423,6 +1432,35 @@ var CertificateAuthority = class {
       });
     }
   }
+  /**
+   * Advertise the validity limits this CA can honor.
+   *
+   * Consumers (notably the GDS server in [`cert_auth.ts`](https://github.com/sterfive/node-opcua-gds))
+   * clamp a requested validity against these bounds before calling
+   * {@link signCertificateRequestFromDER}, so a misconfigured
+   * `defaultCertValidity` cannot ask the CA for something it cannot
+   * produce.
+   *
+   * Defaults match the OpenSSL-backed implementation:
+   * - `minValidityMs = 60_000` (1 minute) — practical floor; the
+   *   X.509 spec floor is 1 second but very short certs are rarely
+   *   useful and pathological for any real deployment.
+   * - `maxValidityMs = 10 * 365 * 86_400_000` (≈ 10 years) — long
+   *   enough for root CAs.
+   * - `validityGranularityMs = 1_000` (1 second) — RFC 5280 §4.1.2.5
+   *   floor on `notBefore` / `notAfter`.
+   * - `nativeUnit = "second"` — what `x509Date()` actually encodes.
+   *
+   * @see US-208 — the consumer-side capability story.
+   */
+  getCapabilities() {
+    return {
+      minValidityMs: 6e4,
+      maxValidityMs: 10 * 365 * 864e5,
+      validityGranularityMs: 1e3,
+      nativeUnit: "second"
+    };
+  }
   /**
    * Generate a new RSA key pair, create an internal CSR, sign it
    * with this CA, and return both the certificate and private key
@@ -1440,7 +1478,6 @@ var CertificateAuthority = class {
    */
   async generateKeyPairAndSignDER(options) {
     const keySize = options.keySize ?? 2048;
-    const validity = options.validity ?? 365;
     const startDate = options.startDate ?? /* @__PURE__ */ new Date();
     const tmpDir = await import_node_fs7.default.promises.mkdtemp(import_node_path5.default.join(import_node_os3.default.tmpdir(), "pki-keygen-"));
     try {
@@ -1460,13 +1497,15 @@ var CertificateAuthority = class {
         purpose: import_node_opcua_crypto2.CertificatePurpose.ForApplication
       });
       const certFile = import_node_path5.default.join(tmpDir, "certificate.pem");
-      await this.signCertificateRequest(certFile, csrFile, {
+      const signingParams = {
         applicationUri: options.applicationUri,
         dns: options.dns,
         ip: options.ip,
-        startDate,
-        validity
-      });
+        startDate
+      };
+      if (options.validityMs !== void 0) signingParams.validityMs = options.validityMs;
+      else signingParams.validity = options.validity ?? 365;
+      await this.signCertificateRequest(certFile, csrFile, signingParams);
       const certPem = (0, import_node_opcua_crypto2.readCertificatePEM)(certFile);
       const certificateDer = (0, import_node_opcua_crypto2.convertPEMtoDER)(certPem);
       const privateKey = (0, import_node_opcua_crypto2.readPrivateKey)(privateKeyFile);
@@ -1491,7 +1530,6 @@ var CertificateAuthority = class {
    */
   async generateKeyPairAndSignPFX(options) {
     const keySize = options.keySize ?? 2048;
-    const validity = options.validity ?? 365;
     const startDate = options.startDate ?? /* @__PURE__ */ new Date();
     const passphrase = options.passphrase ?? "";
     const tmpDir = await import_node_fs7.default.promises.mkdtemp(import_node_path5.default.join(import_node_os3.default.tmpdir(), "pki-keygen-pfx-"));
@@ -1512,13 +1550,15 @@ var CertificateAuthority = class {
         purpose: import_node_opcua_crypto2.CertificatePurpose.ForApplication
       });
       const certFile = import_node_path5.default.join(tmpDir, "certificate.pem");
-      await this.signCertificateRequest(certFile, csrFile, {
+      const signingParams = {
         applicationUri: options.applicationUri,
         dns: options.dns,
         ip: options.ip,
-        startDate,
-        validity
-      });
+        startDate
+      };
+      if (options.validityMs !== void 0) signingParams.validityMs = options.validityMs;
+      else signingParams.validity = options.validity ?? 365;
+      await this.signCertificateRequest(certFile, csrFile, signingParams);
       const pfxFile = import_node_path5.default.join(tmpDir, "bundle.pfx");
       await createPFX({
         certificateFile: certFile,