[debug-certificate-manager] Option to skip automatically trusting and untrusting a certificate

common/changes/@rushstack/debug-certificate-manager/user-apc-skipcerttrust_2024-09-20-22-22.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/debug-certificate-manager",
+      "comment": "Add a `skipCertificateTrust` option to `CertificateManager.ensureCertificateAsync` that skips automatically trusting the generated certificate and untrusting an existing certificate with issues.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/debug-certificate-manager"
+}

common/reviews/api/debug-certificate-manager.api.md

@@ -9,7 +9,7 @@ import type { ITerminal } from '@rushstack/terminal';
 // @public
 export class CertificateManager {
     constructor();
-    ensureCertificateAsync(canGenerateNewCertificate: boolean, terminal: ITerminal, generationOptions?: ICertificateGenerationOptions): Promise<ICertificate>;
+    ensureCertificateAsync(canGenerateNewCertificate: boolean, terminal: ITerminal, options?: ICertificateGenerationOptions): Promise<ICertificate>;
     untrustCertificateAsync(terminal: ITerminal): Promise<boolean>;
 }
 
@@ -39,6 +39,8 @@ export interface ICertificate {
 
 // @public
 export interface ICertificateGenerationOptions {
+    // (undocumented)
+    skipCertificateTrust?: boolean;
     subjectAltNames?: ReadonlyArray<string>;
     subjectIPAddresses?: ReadonlyArray<string>;
     validityInDays?: number;

libraries/debug-certificate-manager/src/CertificateManager.ts

@@ -110,6 +110,10 @@ export interface ICertificateGenerationOptions {
    * How many days the certificate should be valid for.
    */
   validityInDays?: number;
+  /*
+   * Skip trusting a certificate. Defaults to false.
+   */
+  skipCertificateTrust?: boolean;
 }
 
 const MAX_CERTIFICATE_VALIDITY_DAYS: 365 = 365;
@@ -135,10 +139,9 @@ export class CertificateManager {
   public async ensureCertificateAsync(
     canGenerateNewCertificate: boolean,
     terminal: ITerminal,
-    generationOptions?: ICertificateGenerationOptions
+    options?: ICertificateGenerationOptions
   ): Promise<ICertificate> {
-    const optionsWithDefaults: Required<ICertificateGenerationOptions> =
-      applyDefaultOptions(generationOptions);
+    const optionsWithDefaults: Required<ICertificateGenerationOptions> = applyDefaultOptions(options);
 
     const { certificateData: existingCert, keyData: existingKey } = this._certificateStore;
 
@@ -226,7 +229,9 @@ export class CertificateManager {
         if (canGenerateNewCertificate) {
           messages.push('Attempting to untrust the certificate and generate a new one.');
           terminal.writeWarningLine(messages.join(' '));
-          await this.untrustCertificateAsync(terminal);
+          if (!options?.skipCertificateTrust) {
+            await this.untrustCertificateAsync(terminal);
+          }
           return await this._ensureCertificateInternalAsync(optionsWithDefaults, terminal);
         } else {
           messages.push(
@@ -732,10 +737,9 @@ export class CertificateManager {
       });
     }
 
-    const trustCertificateResult: boolean = await this._tryTrustCertificateAsync(
-      tempCertificatePath,
-      terminal
-    );
+    const trustCertificateResult: boolean = options.skipCertificateTrust
+      ? true
+      : await this._tryTrustCertificateAsync(tempCertificatePath, terminal);
 
     let subjectAltNames: readonly string[] | undefined;
     if (trustCertificateResult) {
@@ -787,6 +791,7 @@ function applyDefaultOptions(
 ): Required<ICertificateGenerationOptions> {
   const subjectNames: ReadonlyArray<string> | undefined = options?.subjectAltNames;
   const subjectIpAddresses: ReadonlyArray<string> | undefined = options?.subjectIPAddresses;
+  const skipCertificateTrust: boolean | undefined = options?.skipCertificateTrust || false;
   return {
     subjectAltNames: subjectNames?.length ? subjectNames : DEFAULT_CERTIFICATE_SUBJECT_NAMES,
     subjectIPAddresses: subjectIpAddresses?.length
@@ -795,7 +800,8 @@ function applyDefaultOptions(
     validityInDays: Math.min(
       MAX_CERTIFICATE_VALIDITY_DAYS,
       options?.validityInDays ?? MAX_CERTIFICATE_VALIDITY_DAYS
-    )
+    ),
+    skipCertificateTrust: skipCertificateTrust
   };
 }