node-opcua-pki 6.14.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.
@@ -161,6 +172,28 @@ interface CertificateAuthorityOptions {
      * The parent CA must be initialized before this CA.
      */
     issuerCA?: CertificateAuthority;
+    /**
+     * Public URL (http/https) where the CRL produced by this CA is
+     * reachable. When set, every issued certificate carries an
+     * X.509v3 `crlDistributionPoints` extension pointing at this URL.
+     *
+     * Leave undefined to omit the extension entirely (opt-in — see
+     * US-202).  Validated synchronously at construction / setter call.
+     */
+    crlDistributionUrl?: string;
+    /**
+     * Public URL of the OCSP responder. When set, every issued cert
+     * carries an `authorityInfoAccess` extension with an `OCSP` leg
+     * pointing at this URL. Leave undefined to omit (US-202).
+     */
+    ocspResponderUrl?: string;
+    /**
+     * Public URL where the issuer's certificate can be fetched.
+     * When set, the `authorityInfoAccess` extension on every issued
+     * cert carries a `caIssuers` leg pointing at this URL (chain
+     * repair). Leave undefined to omit (US-202).
+     */
+    caIssuersUrl?: string;
 }
 /**
  * An OpenSSL-based Certificate Authority (CA) that can create,
@@ -218,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. */
@@ -229,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}.
  */
@@ -243,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). */
@@ -270,7 +345,61 @@ declare class CertificateAuthority {
     readonly subject: Subject;
     /** @internal Parent CA (undefined for root CAs). */
     readonly _issuerCA?: CertificateAuthority;
+    /** @internal Configured CDP / AIA URLs (US-202). */
+    private _crlDistributionUrl?;
+    private _ocspResponderUrl?;
+    private _caIssuersUrl?;
     constructor(options: CertificateAuthorityOptions);
+    /**
+     * Public URL where the CRL produced by this CA is reachable, or
+     * `undefined` if no CDP extension should be emitted on issued certs.
+     */
+    get crlDistributionUrl(): string | undefined;
+    /**
+     * Public URL of the OCSP responder, or `undefined` if no AIA OCSP
+     * leg should be emitted on issued certs.
+     */
+    get ocspResponderUrl(): string | undefined;
+    /**
+     * Public URL where the issuer's certificate can be fetched, or
+     * `undefined` if no AIA caIssuers leg should be emitted.
+     */
+    get caIssuersUrl(): string | undefined;
+    /**
+     * Configure the URL embedded as `crlDistributionPoints` in every
+     * subsequently-issued certificate. Pass `undefined` to disable
+     * the extension entirely. Validated synchronously — throws on
+     * empty string, non-http(s) protocol, missing path. Warns (does
+     * not throw) when the URL points at loopback.
+     *
+     * @see US-202
+     */
+    setCrlDistributionUrl(url: string | undefined): void;
+    /**
+     * Configure the OCSP responder URL embedded as the `OCSP` leg of
+     * the `authorityInfoAccess` extension on every subsequently-issued
+     * certificate. Pass `undefined` to disable.
+     *
+     * @see US-202
+     */
+    setOcspResponderUrl(url: string | undefined): void;
+    /**
+     * Configure the caIssuers URL embedded as the `caIssuers` leg of
+     * the `authorityInfoAccess` extension on every subsequently-issued
+     * certificate. Pass `undefined` to disable.
+     *
+     * @see US-202
+     */
+    setCaIssuersUrl(url: string | undefined): void;
+    /**
+     * @internal
+     * Populate the OpenSSL config substitution env vars (`CDP_URL` and
+     * `AIA_VALUE`) from the configured URLs, or unset them so the
+     * matching `{{#KEY}}...{{/KEY}}` blocks in the templates are
+     * stripped. MUST be called before every `generateStaticConfig`
+     * invocation that signs a certificate.
+     */
+    _wireRevocationEnvVars(): void;
     /** Absolute path to the CA root directory (alias for {@link location}). */
     get rootDir(): string;
     /** Path to the OpenSSL configuration file (`conf/caconfig.cnf`). */
@@ -399,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
@@ -1364,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.
@@ -161,6 +172,28 @@ interface CertificateAuthorityOptions {
      * The parent CA must be initialized before this CA.
      */
     issuerCA?: CertificateAuthority;
+    /**
+     * Public URL (http/https) where the CRL produced by this CA is
+     * reachable. When set, every issued certificate carries an
+     * X.509v3 `crlDistributionPoints` extension pointing at this URL.
+     *
+     * Leave undefined to omit the extension entirely (opt-in — see
+     * US-202).  Validated synchronously at construction / setter call.
+     */
+    crlDistributionUrl?: string;
+    /**
+     * Public URL of the OCSP responder. When set, every issued cert
+     * carries an `authorityInfoAccess` extension with an `OCSP` leg
+     * pointing at this URL. Leave undefined to omit (US-202).
+     */
+    ocspResponderUrl?: string;
+    /**
+     * Public URL where the issuer's certificate can be fetched.
+     * When set, the `authorityInfoAccess` extension on every issued
+     * cert carries a `caIssuers` leg pointing at this URL (chain
+     * repair). Leave undefined to omit (US-202).
+     */
+    caIssuersUrl?: string;
 }
 /**
  * An OpenSSL-based Certificate Authority (CA) that can create,
@@ -218,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. */
@@ -229,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}.
  */
@@ -243,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). */
@@ -270,7 +345,61 @@ declare class CertificateAuthority {
     readonly subject: Subject;
     /** @internal Parent CA (undefined for root CAs). */
     readonly _issuerCA?: CertificateAuthority;
+    /** @internal Configured CDP / AIA URLs (US-202). */
+    private _crlDistributionUrl?;
+    private _ocspResponderUrl?;
+    private _caIssuersUrl?;
     constructor(options: CertificateAuthorityOptions);
+    /**
+     * Public URL where the CRL produced by this CA is reachable, or
+     * `undefined` if no CDP extension should be emitted on issued certs.
+     */
+    get crlDistributionUrl(): string | undefined;
+    /**
+     * Public URL of the OCSP responder, or `undefined` if no AIA OCSP
+     * leg should be emitted on issued certs.
+     */
+    get ocspResponderUrl(): string | undefined;
+    /**
+     * Public URL where the issuer's certificate can be fetched, or
+     * `undefined` if no AIA caIssuers leg should be emitted.
+     */
+    get caIssuersUrl(): string | undefined;
+    /**
+     * Configure the URL embedded as `crlDistributionPoints` in every
+     * subsequently-issued certificate. Pass `undefined` to disable
+     * the extension entirely. Validated synchronously — throws on
+     * empty string, non-http(s) protocol, missing path. Warns (does
+     * not throw) when the URL points at loopback.
+     *
+     * @see US-202
+     */
+    setCrlDistributionUrl(url: string | undefined): void;
+    /**
+     * Configure the OCSP responder URL embedded as the `OCSP` leg of
+     * the `authorityInfoAccess` extension on every subsequently-issued
+     * certificate. Pass `undefined` to disable.
+     *
+     * @see US-202
+     */
+    setOcspResponderUrl(url: string | undefined): void;
+    /**
+     * Configure the caIssuers URL embedded as the `caIssuers` leg of
+     * the `authorityInfoAccess` extension on every subsequently-issued
+     * certificate. Pass `undefined` to disable.
+     *
+     * @see US-202
+     */
+    setCaIssuersUrl(url: string | undefined): void;
+    /**
+     * @internal
+     * Populate the OpenSSL config substitution env vars (`CDP_URL` and
+     * `AIA_VALUE`) from the configured URLs, or unset them so the
+     * matching `{{#KEY}}...{{/KEY}}` blocks in the templates are
+     * stripped. MUST be called before every `generateStaticConfig`
+     * invocation that signs a certificate.
+     */
+    _wireRevocationEnvVars(): void;
     /** Absolute path to the CA root directory (alias for {@link location}). */
     get rootDir(): string;
     /** Path to the OpenSSL configuration file (`conf/caconfig.cnf`). */
@@ -399,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
@@ -1364,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 };