node-opcua-pki 6.10.2 → 6.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { SubjectOptions, CertificatePurpose, Subject, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
1
+ import { SubjectOptions, CertificatePurpose, Subject, PrivateKey, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
2
2
  export { Subject, SubjectOptions } from 'node-opcua-crypto';
3
3
  import { EventEmitter } from 'node:events';
4
4
 
@@ -103,6 +103,42 @@ interface Params extends ProcessAltNamesParam, StartDateEndDateParam {
103
103
  declare function adjustDate(params: StartDateEndDateParam): void;
104
104
  declare function adjustApplicationUri(params: Params): void;
105
105
 
106
+ /**
107
+ * Result of {@link CertificateAuthority.initializeCSR}.
108
+ *
109
+ * - `"ready"` — the CA certificate already exists and is valid.
110
+ * - `"pending"` — key + CSR exist but no cert; waiting for external signing.
111
+ * - `"created"` — a fresh key + CSR were just generated.
112
+ * - `"expired"` — the CA certificate has expired (or will expire within
113
+ * the configured threshold). A new CSR has been generated for renewal
114
+ * while preserving the existing private key.
115
+ */
116
+ type InitializeCSRResult = {
117
+ status: "ready";
118
+ } | {
119
+ status: "pending";
120
+ csrPath: string;
121
+ } | {
122
+ status: "created";
123
+ csrPath: string;
124
+ } | {
125
+ status: "expired";
126
+ csrPath: string;
127
+ expiryDate: Date;
128
+ };
129
+ /**
130
+ * Result of {@link CertificateAuthority.installCACertificate}.
131
+ *
132
+ * - `"success"` — the certificate was installed and CRL generated.
133
+ * - `"error"` — the certificate was rejected (see `reason`).
134
+ */
135
+ type InstallCACertificateResult = {
136
+ status: "success";
137
+ } | {
138
+ status: "error";
139
+ reason: string;
140
+ message: string;
141
+ };
106
142
  /**
107
143
  * Options for creating a {@link CertificateAuthority}.
108
144
  */
@@ -119,6 +155,12 @@ interface CertificateAuthorityOptions {
119
155
  * @defaultValue {@link defaultSubject}
120
156
  */
121
157
  subject?: string | SubjectOptions;
158
+ /**
159
+ * Parent CA that will sign this CA's certificate.
160
+ * If omitted, the CA is self-signed (root CA).
161
+ * The parent CA must be initialized before this CA.
162
+ */
163
+ issuerCA?: CertificateAuthority;
122
164
  }
123
165
  /**
124
166
  * An OpenSSL-based Certificate Authority (CA) that can create,
@@ -167,6 +209,58 @@ interface IssuedCertificateRecord {
167
209
  */
168
210
  revocationDate?: string;
169
211
  }
212
+ /**
213
+ * Options for {@link CertificateAuthority.signCertificateRequestFromDER}.
214
+ *
215
+ * All fields are optional. When provided, they override the
216
+ * corresponding values from the CSR.
217
+ */
218
+ interface SignCertificateOptions {
219
+ /** Certificate validity in days (default: 365). */
220
+ validity?: number;
221
+ /** Override the certificate start date. */
222
+ startDate?: Date;
223
+ /** Override DNS SANs. */
224
+ dns?: string[];
225
+ /** Override IP SANs. */
226
+ ip?: string[];
227
+ /** Override the application URI SAN. */
228
+ applicationUri?: string;
229
+ /** Override the X.500 subject. */
230
+ subject?: SubjectOptions | string;
231
+ }
232
+ /**
233
+ * Options for {@link CertificateAuthority.generateKeyPairAndSignDER}.
234
+ */
235
+ interface GenerateKeyPairAndSignOptions {
236
+ /** OPC UA application URI (required). */
237
+ applicationUri: string;
238
+ /** X.500 subject for the certificate (e.g. "CN=MyApp"). */
239
+ subject?: SubjectOptions | string;
240
+ /** DNS host names for the SAN extension. */
241
+ dns?: string[];
242
+ /** IP addresses for the SAN extension. */
243
+ ip?: string[];
244
+ /** Certificate validity in days (default: 365). */
245
+ validity?: number;
246
+ /** Certificate start date (default: now). */
247
+ startDate?: Date;
248
+ /** RSA key size in bits (default: 2048). */
249
+ keySize?: KeySize;
250
+ }
251
+ /**
252
+ * Options for {@link CertificateAuthority.generateKeyPairAndSignPFX}.
253
+ *
254
+ * Extends the DER options with an optional `passphrase` to protect
255
+ * the PFX bundle.
256
+ */
257
+ interface GenerateKeyPairAndSignPFXOptions extends GenerateKeyPairAndSignOptions {
258
+ /**
259
+ * Passphrase to protect the PFX file.
260
+ * If omitted, the PFX is created without a password.
261
+ */
262
+ passphrase?: string;
263
+ }
170
264
  declare class CertificateAuthority {
171
265
  /** RSA key size used when generating the CA private key. */
172
266
  readonly keySize: KeySize;
@@ -174,6 +268,8 @@ declare class CertificateAuthority {
174
268
  readonly location: string;
175
269
  /** X.500 subject of the CA certificate. */
176
270
  readonly subject: Subject;
271
+ /** @internal Parent CA (undefined for root CAs). */
272
+ readonly _issuerCA?: CertificateAuthority;
177
273
  constructor(options: CertificateAuthorityOptions);
178
274
  /** Absolute path to the CA root directory (alias for {@link location}). */
179
275
  get rootDir(): string;
@@ -181,6 +277,16 @@ declare class CertificateAuthority {
181
277
  get configFile(): string;
182
278
  /** Path to the CA certificate in PEM format (`public/cacert.pem`). */
183
279
  get caCertificate(): string;
280
+ /**
281
+ * Path to the issuer certificate chain (`public/issuer_chain.pem`).
282
+ *
283
+ * This file is created by {@link installCACertificate} when the
284
+ * provided cert file contains additional issuer certificates
285
+ * (e.g. intermediate + root). It is appended to signed certs
286
+ * by {@link constructCertificateChain} to produce a full chain
287
+ * per OPC UA Part 6 §6.2.6.
288
+ */
289
+ get issuerCertificateChain(): string;
184
290
  /**
185
291
  * Path to the current Certificate Revocation List in DER format.
186
292
  * (`crl/revocation_list.der`)
@@ -284,15 +390,46 @@ declare class CertificateAuthority {
284
390
  * internally so that callers can work with in-memory
285
391
  * buffers only.
286
392
  *
393
+ * The CA can override fields from the CSR by passing
394
+ * `options.dns`, `options.ip`, `options.applicationUri`,
395
+ * `options.startDate`, or `options.subject`.
396
+ *
287
397
  * @param csrDer - the CSR as a DER-encoded buffer
288
- * @param options - signing options
289
- * @param options.validity - certificate validity in days
290
- * (default: 365)
398
+ * @param options - signing options and CA overrides
291
399
  * @returns the signed certificate as a DER-encoded buffer
292
400
  */
293
- signCertificateRequestFromDER(csrDer: Buffer, options?: {
294
- validity?: number;
295
- }): Promise<Buffer>;
401
+ signCertificateRequestFromDER(csrDer: Buffer, options?: SignCertificateOptions): Promise<Buffer>;
402
+ /**
403
+ * Generate a new RSA key pair, create an internal CSR, sign it
404
+ * with this CA, and return both the certificate and private key
405
+ * as DER-encoded buffers.
406
+ *
407
+ * The private key is **never stored** by the CA — it exists only
408
+ * in a temporary directory that is cleaned up after the operation.
409
+ *
410
+ * This is used by `StartNewKeyPairRequest` (OPC UA Part 12) for
411
+ * constrained devices that cannot generate their own keys.
412
+ *
413
+ * @param options - key generation and certificate parameters
414
+ * @returns `{ certificateDer, privateKey }` — certificate as DER,
415
+ * private key as a branded `PrivateKey` buffer
416
+ */
417
+ generateKeyPairAndSignDER(options: GenerateKeyPairAndSignOptions): Promise<{
418
+ certificateDer: Buffer;
419
+ privateKey: PrivateKey;
420
+ }>;
421
+ /**
422
+ * Generate a new RSA key pair, create an internal CSR, sign it
423
+ * with this CA, and return the result as a PKCS#12 (PFX)
424
+ * buffer bundling the certificate, private key, and CA chain.
425
+ *
426
+ * The private key is **never stored** by the CA — it exists only
427
+ * in a temporary directory that is cleaned up after the operation.
428
+ *
429
+ * @param options - key generation, certificate, and PFX options
430
+ * @returns the PFX as a `Buffer`
431
+ */
432
+ generateKeyPairAndSignPFX(options: GenerateKeyPairAndSignPFXOptions): Promise<Buffer>;
296
433
  /**
297
434
  * Revoke a DER-encoded certificate and regenerate the CRL.
298
435
  *
@@ -312,6 +449,78 @@ declare class CertificateAuthority {
312
449
  * already exist.
313
450
  */
314
451
  initialize(): Promise<void>;
452
+ /**
453
+ * Initialize the CA directory structure and generate the
454
+ * private key + CSR **without signing**.
455
+ *
456
+ * Use this when the CA certificate will be signed by an
457
+ * external (third-party) root CA. After receiving the signed
458
+ * certificate, call {@link installCACertificate} to complete
459
+ * the setup.
460
+ *
461
+ * **Idempotent / restart-safe:**
462
+ * - If the CA certificate exists and is valid → `{ status: "ready" }`
463
+ * - If the CA certificate has expired → `{ status: "expired", csrPath, expiryDate }`
464
+ * (a new CSR is generated, preserving the existing private key)
465
+ * - If key + CSR exist but no cert (restart before install) →
466
+ * `{ status: "pending", csrPath }` without regenerating
467
+ * - Otherwise → generates key + CSR → `{ status: "created", csrPath }`
468
+ *
469
+ * @returns an {@link InitializeCSRResult} describing the CA state
470
+ */
471
+ initializeCSR(): Promise<InitializeCSRResult>;
472
+ /**
473
+ * Check whether the CA certificate needs renewal and, if so,
474
+ * generate a new CSR for re-signing by the external root CA.
475
+ *
476
+ * Use this while the CA is running to detect upcoming expiry
477
+ * **before** it actually expires. The existing private key is
478
+ * preserved so previously issued certs remain valid.
479
+ *
480
+ * @param thresholdDays - number of days before expiry at which
481
+ * to trigger renewal (default: 30)
482
+ * @returns an {@link InitializeCSRResult} — `"expired"` if
483
+ * renewal is needed, `"ready"` if the cert is still valid
484
+ */
485
+ renewCSR(thresholdDays?: number): Promise<InitializeCSRResult>;
486
+ /**
487
+ * Generate a CSR using the existing private key.
488
+ * @internal
489
+ */
490
+ private _generateCSR;
491
+ /**
492
+ * Install an externally-signed CA certificate and generate
493
+ * the initial CRL.
494
+ *
495
+ * Call this after {@link initializeCSR} once the external
496
+ * root CA has signed the CSR.
497
+ *
498
+ * **Safety checks:**
499
+ * - Verifies that the certificate's public key matches the
500
+ * CA private key before installing.
501
+ *
502
+ * @param signedCertFile - path to the PEM-encoded signed
503
+ * CA certificate (issued by the external root CA)
504
+ * @returns an {@link InstallCACertificateResult} with
505
+ * `status: "success"` or `status: "error"` and a `reason`
506
+ */
507
+ installCACertificate(signedCertFile: string): Promise<InstallCACertificateResult>;
508
+ /**
509
+ * Sign a CSR with CA extensions (`v3_ca`), producing a
510
+ * subordinate CA certificate.
511
+ *
512
+ * Unlike {@link signCertificateRequest} which signs with
513
+ * end-entity extensions (SANs, etc.), this method signs
514
+ * with `basicConstraints = CA:TRUE` and `keyUsage =
515
+ * keyCertSign, cRLSign`.
516
+ *
517
+ * @param certFile - output path for the signed CA cert (PEM)
518
+ * @param csrFile - path to the subordinate CA's CSR
519
+ * @param params - signing parameters
520
+ */
521
+ signCACertificateRequest(certFile: string, csrFile: string, params: {
522
+ validity?: number;
523
+ }): Promise<void>;
315
524
  /**
316
525
  * Rebuild the combined CA certificate + CRL file.
317
526
  *
@@ -1014,4 +1223,4 @@ declare function dumpPFX(pfxFile: Filename, passphrase?: string): Promise<string
1014
1223
  */
1015
1224
  declare function install_prerequisite(): Promise<string>;
1016
1225
 
1017
- export { CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type KeyLength, type KeySize, type Params, type ProcessAltNamesParam, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, quote };
1226
+ export { CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, 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, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, quote };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { SubjectOptions, CertificatePurpose, Subject, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
1
+ import { SubjectOptions, CertificatePurpose, Subject, PrivateKey, Certificate, DER, CertificateRevocationList } from 'node-opcua-crypto';
2
2
  export { Subject, SubjectOptions } from 'node-opcua-crypto';
3
3
  import { EventEmitter } from 'node:events';
4
4
 
@@ -103,6 +103,42 @@ interface Params extends ProcessAltNamesParam, StartDateEndDateParam {
103
103
  declare function adjustDate(params: StartDateEndDateParam): void;
104
104
  declare function adjustApplicationUri(params: Params): void;
105
105
 
106
+ /**
107
+ * Result of {@link CertificateAuthority.initializeCSR}.
108
+ *
109
+ * - `"ready"` — the CA certificate already exists and is valid.
110
+ * - `"pending"` — key + CSR exist but no cert; waiting for external signing.
111
+ * - `"created"` — a fresh key + CSR were just generated.
112
+ * - `"expired"` — the CA certificate has expired (or will expire within
113
+ * the configured threshold). A new CSR has been generated for renewal
114
+ * while preserving the existing private key.
115
+ */
116
+ type InitializeCSRResult = {
117
+ status: "ready";
118
+ } | {
119
+ status: "pending";
120
+ csrPath: string;
121
+ } | {
122
+ status: "created";
123
+ csrPath: string;
124
+ } | {
125
+ status: "expired";
126
+ csrPath: string;
127
+ expiryDate: Date;
128
+ };
129
+ /**
130
+ * Result of {@link CertificateAuthority.installCACertificate}.
131
+ *
132
+ * - `"success"` — the certificate was installed and CRL generated.
133
+ * - `"error"` — the certificate was rejected (see `reason`).
134
+ */
135
+ type InstallCACertificateResult = {
136
+ status: "success";
137
+ } | {
138
+ status: "error";
139
+ reason: string;
140
+ message: string;
141
+ };
106
142
  /**
107
143
  * Options for creating a {@link CertificateAuthority}.
108
144
  */
@@ -119,6 +155,12 @@ interface CertificateAuthorityOptions {
119
155
  * @defaultValue {@link defaultSubject}
120
156
  */
121
157
  subject?: string | SubjectOptions;
158
+ /**
159
+ * Parent CA that will sign this CA's certificate.
160
+ * If omitted, the CA is self-signed (root CA).
161
+ * The parent CA must be initialized before this CA.
162
+ */
163
+ issuerCA?: CertificateAuthority;
122
164
  }
123
165
  /**
124
166
  * An OpenSSL-based Certificate Authority (CA) that can create,
@@ -167,6 +209,58 @@ interface IssuedCertificateRecord {
167
209
  */
168
210
  revocationDate?: string;
169
211
  }
212
+ /**
213
+ * Options for {@link CertificateAuthority.signCertificateRequestFromDER}.
214
+ *
215
+ * All fields are optional. When provided, they override the
216
+ * corresponding values from the CSR.
217
+ */
218
+ interface SignCertificateOptions {
219
+ /** Certificate validity in days (default: 365). */
220
+ validity?: number;
221
+ /** Override the certificate start date. */
222
+ startDate?: Date;
223
+ /** Override DNS SANs. */
224
+ dns?: string[];
225
+ /** Override IP SANs. */
226
+ ip?: string[];
227
+ /** Override the application URI SAN. */
228
+ applicationUri?: string;
229
+ /** Override the X.500 subject. */
230
+ subject?: SubjectOptions | string;
231
+ }
232
+ /**
233
+ * Options for {@link CertificateAuthority.generateKeyPairAndSignDER}.
234
+ */
235
+ interface GenerateKeyPairAndSignOptions {
236
+ /** OPC UA application URI (required). */
237
+ applicationUri: string;
238
+ /** X.500 subject for the certificate (e.g. "CN=MyApp"). */
239
+ subject?: SubjectOptions | string;
240
+ /** DNS host names for the SAN extension. */
241
+ dns?: string[];
242
+ /** IP addresses for the SAN extension. */
243
+ ip?: string[];
244
+ /** Certificate validity in days (default: 365). */
245
+ validity?: number;
246
+ /** Certificate start date (default: now). */
247
+ startDate?: Date;
248
+ /** RSA key size in bits (default: 2048). */
249
+ keySize?: KeySize;
250
+ }
251
+ /**
252
+ * Options for {@link CertificateAuthority.generateKeyPairAndSignPFX}.
253
+ *
254
+ * Extends the DER options with an optional `passphrase` to protect
255
+ * the PFX bundle.
256
+ */
257
+ interface GenerateKeyPairAndSignPFXOptions extends GenerateKeyPairAndSignOptions {
258
+ /**
259
+ * Passphrase to protect the PFX file.
260
+ * If omitted, the PFX is created without a password.
261
+ */
262
+ passphrase?: string;
263
+ }
170
264
  declare class CertificateAuthority {
171
265
  /** RSA key size used when generating the CA private key. */
172
266
  readonly keySize: KeySize;
@@ -174,6 +268,8 @@ declare class CertificateAuthority {
174
268
  readonly location: string;
175
269
  /** X.500 subject of the CA certificate. */
176
270
  readonly subject: Subject;
271
+ /** @internal Parent CA (undefined for root CAs). */
272
+ readonly _issuerCA?: CertificateAuthority;
177
273
  constructor(options: CertificateAuthorityOptions);
178
274
  /** Absolute path to the CA root directory (alias for {@link location}). */
179
275
  get rootDir(): string;
@@ -181,6 +277,16 @@ declare class CertificateAuthority {
181
277
  get configFile(): string;
182
278
  /** Path to the CA certificate in PEM format (`public/cacert.pem`). */
183
279
  get caCertificate(): string;
280
+ /**
281
+ * Path to the issuer certificate chain (`public/issuer_chain.pem`).
282
+ *
283
+ * This file is created by {@link installCACertificate} when the
284
+ * provided cert file contains additional issuer certificates
285
+ * (e.g. intermediate + root). It is appended to signed certs
286
+ * by {@link constructCertificateChain} to produce a full chain
287
+ * per OPC UA Part 6 §6.2.6.
288
+ */
289
+ get issuerCertificateChain(): string;
184
290
  /**
185
291
  * Path to the current Certificate Revocation List in DER format.
186
292
  * (`crl/revocation_list.der`)
@@ -284,15 +390,46 @@ declare class CertificateAuthority {
284
390
  * internally so that callers can work with in-memory
285
391
  * buffers only.
286
392
  *
393
+ * The CA can override fields from the CSR by passing
394
+ * `options.dns`, `options.ip`, `options.applicationUri`,
395
+ * `options.startDate`, or `options.subject`.
396
+ *
287
397
  * @param csrDer - the CSR as a DER-encoded buffer
288
- * @param options - signing options
289
- * @param options.validity - certificate validity in days
290
- * (default: 365)
398
+ * @param options - signing options and CA overrides
291
399
  * @returns the signed certificate as a DER-encoded buffer
292
400
  */
293
- signCertificateRequestFromDER(csrDer: Buffer, options?: {
294
- validity?: number;
295
- }): Promise<Buffer>;
401
+ signCertificateRequestFromDER(csrDer: Buffer, options?: SignCertificateOptions): Promise<Buffer>;
402
+ /**
403
+ * Generate a new RSA key pair, create an internal CSR, sign it
404
+ * with this CA, and return both the certificate and private key
405
+ * as DER-encoded buffers.
406
+ *
407
+ * The private key is **never stored** by the CA — it exists only
408
+ * in a temporary directory that is cleaned up after the operation.
409
+ *
410
+ * This is used by `StartNewKeyPairRequest` (OPC UA Part 12) for
411
+ * constrained devices that cannot generate their own keys.
412
+ *
413
+ * @param options - key generation and certificate parameters
414
+ * @returns `{ certificateDer, privateKey }` — certificate as DER,
415
+ * private key as a branded `PrivateKey` buffer
416
+ */
417
+ generateKeyPairAndSignDER(options: GenerateKeyPairAndSignOptions): Promise<{
418
+ certificateDer: Buffer;
419
+ privateKey: PrivateKey;
420
+ }>;
421
+ /**
422
+ * Generate a new RSA key pair, create an internal CSR, sign it
423
+ * with this CA, and return the result as a PKCS#12 (PFX)
424
+ * buffer bundling the certificate, private key, and CA chain.
425
+ *
426
+ * The private key is **never stored** by the CA — it exists only
427
+ * in a temporary directory that is cleaned up after the operation.
428
+ *
429
+ * @param options - key generation, certificate, and PFX options
430
+ * @returns the PFX as a `Buffer`
431
+ */
432
+ generateKeyPairAndSignPFX(options: GenerateKeyPairAndSignPFXOptions): Promise<Buffer>;
296
433
  /**
297
434
  * Revoke a DER-encoded certificate and regenerate the CRL.
298
435
  *
@@ -312,6 +449,78 @@ declare class CertificateAuthority {
312
449
  * already exist.
313
450
  */
314
451
  initialize(): Promise<void>;
452
+ /**
453
+ * Initialize the CA directory structure and generate the
454
+ * private key + CSR **without signing**.
455
+ *
456
+ * Use this when the CA certificate will be signed by an
457
+ * external (third-party) root CA. After receiving the signed
458
+ * certificate, call {@link installCACertificate} to complete
459
+ * the setup.
460
+ *
461
+ * **Idempotent / restart-safe:**
462
+ * - If the CA certificate exists and is valid → `{ status: "ready" }`
463
+ * - If the CA certificate has expired → `{ status: "expired", csrPath, expiryDate }`
464
+ * (a new CSR is generated, preserving the existing private key)
465
+ * - If key + CSR exist but no cert (restart before install) →
466
+ * `{ status: "pending", csrPath }` without regenerating
467
+ * - Otherwise → generates key + CSR → `{ status: "created", csrPath }`
468
+ *
469
+ * @returns an {@link InitializeCSRResult} describing the CA state
470
+ */
471
+ initializeCSR(): Promise<InitializeCSRResult>;
472
+ /**
473
+ * Check whether the CA certificate needs renewal and, if so,
474
+ * generate a new CSR for re-signing by the external root CA.
475
+ *
476
+ * Use this while the CA is running to detect upcoming expiry
477
+ * **before** it actually expires. The existing private key is
478
+ * preserved so previously issued certs remain valid.
479
+ *
480
+ * @param thresholdDays - number of days before expiry at which
481
+ * to trigger renewal (default: 30)
482
+ * @returns an {@link InitializeCSRResult} — `"expired"` if
483
+ * renewal is needed, `"ready"` if the cert is still valid
484
+ */
485
+ renewCSR(thresholdDays?: number): Promise<InitializeCSRResult>;
486
+ /**
487
+ * Generate a CSR using the existing private key.
488
+ * @internal
489
+ */
490
+ private _generateCSR;
491
+ /**
492
+ * Install an externally-signed CA certificate and generate
493
+ * the initial CRL.
494
+ *
495
+ * Call this after {@link initializeCSR} once the external
496
+ * root CA has signed the CSR.
497
+ *
498
+ * **Safety checks:**
499
+ * - Verifies that the certificate's public key matches the
500
+ * CA private key before installing.
501
+ *
502
+ * @param signedCertFile - path to the PEM-encoded signed
503
+ * CA certificate (issued by the external root CA)
504
+ * @returns an {@link InstallCACertificateResult} with
505
+ * `status: "success"` or `status: "error"` and a `reason`
506
+ */
507
+ installCACertificate(signedCertFile: string): Promise<InstallCACertificateResult>;
508
+ /**
509
+ * Sign a CSR with CA extensions (`v3_ca`), producing a
510
+ * subordinate CA certificate.
511
+ *
512
+ * Unlike {@link signCertificateRequest} which signs with
513
+ * end-entity extensions (SANs, etc.), this method signs
514
+ * with `basicConstraints = CA:TRUE` and `keyUsage =
515
+ * keyCertSign, cRLSign`.
516
+ *
517
+ * @param certFile - output path for the signed CA cert (PEM)
518
+ * @param csrFile - path to the subordinate CA's CSR
519
+ * @param params - signing parameters
520
+ */
521
+ signCACertificateRequest(certFile: string, csrFile: string, params: {
522
+ validity?: number;
523
+ }): Promise<void>;
315
524
  /**
316
525
  * Rebuild the combined CA certificate + CRL file.
317
526
  *
@@ -1014,4 +1223,4 @@ declare function dumpPFX(pfxFile: Filename, passphrase?: string): Promise<string
1014
1223
  */
1015
1224
  declare function install_prerequisite(): Promise<string>;
1016
1225
 
1017
- export { CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, type CreateCertificateSigningRequestOptions, type CreateCertificateSigningRequestWithConfigOptions, type CreatePFXOptions, type CreateSelfSignCertificateParam, type CreateSelfSignCertificateParam1, type CreateSelfSignCertificateWithConfigParam, type CrlStore, type ExtractPFXOptions, type ExtractPFXResult, type Filename, type KeyLength, type KeySize, type Params, type ProcessAltNamesParam, type StartDateEndDateParam, type Thumbprint, VerificationStatus, type VerifyCertificateOptions, adjustApplicationUri, adjustDate, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, quote };
1226
+ export { CertificateAuthority, type CertificateAuthorityOptions, CertificateManager, type CertificateManagerEvents, type CertificateManagerOptions, CertificateManagerState, type CertificateStatus, type CertificateStore, 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, convertPFXtoPEM, createPFX, dumpPFX, extractAllFromPFX, extractCACertificatesFromPFX, extractCertificateFromPFX, extractPrivateKeyFromPFX, findIssuerCertificateInChain, install_prerequisite, quote };