chore(cli): use typed errors ToolkitError and AuthenticationError in CLI (#32548)

Closes #32347

This PR creates two new error types, `ToolkitError` and
`AuthenticationError` and uses them in `aws-cdk`.

### Checklist
- [x] My code adheres to the [CONTRIBUTING
GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and
[DESIGN
GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license*

---------

Signed-off-by: Sumu <[email protected]>
Co-authored-by: Momo Kornher <[email protected]>

Author: sumupitchayan

packages/aws-cdk/lib/api/aws-auth/awscli-compatible.ts

@@ -9,6 +9,7 @@ import { makeCachingProvider } from './provider-caching';
 import type { SdkHttpOptions } from './sdk-provider';
 import { readIfPossible } from './util';
 import { debug } from '../../logging';
+import { AuthenticationError } from '../../toolkit/error';
 
 const DEFAULT_CONNECTION_TIMEOUT = 10000;
 const DEFAULT_TIMEOUT = 300000;
@@ -291,7 +292,7 @@ async function tokenCodeFn(serialArn: string): Promise<string> {
     return token;
   } catch (err: any) {
     debug('Failed to get MFA token', err);
-    const e = new Error(`Error fetching MFA token: ${err.message ?? err}`);
+    const e = new AuthenticationError(`Error fetching MFA token: ${err.message ?? err}`);
     e.name = 'SharedIniFileCredentialsProviderFailure';
     throw e;
   }

packages/aws-cdk/lib/api/aws-auth/credential-plugins.ts

@@ -3,6 +3,7 @@ import type { AwsCredentialIdentity, AwsCredentialIdentityProvider } from '@smit
 import { debug, warning } from '../../logging';
 import { CredentialProviderSource, PluginProviderResult, Mode, PluginHost, SDKv2CompatibleCredentials, SDKv3CompatibleCredentialProvider, SDKv3CompatibleCredentials } from '../plugin';
 import { credentialsAboutToExpire, makeCachingProvider } from './provider-caching';
+import { AuthenticationError } from '../../toolkit/error';
 
 /**
  * Cache for credential providers.
@@ -124,7 +125,7 @@ async function v3ProviderFromPlugin(producer: () => Promise<PluginProviderResult
     // V2 credentials that refresh and cache themselves
     return v3ProviderFromV2Credentials(initial);
   } else {
-    throw new Error(`Plugin returned a value that doesn't resemble AWS credentials: ${inspect(initial)}`);
+    throw new AuthenticationError(`Plugin returned a value that doesn't resemble AWS credentials: ${inspect(initial)}`);
   }
 }
 
@@ -152,7 +153,7 @@ function refreshFromPluginProvider(current: AwsCredentialIdentity, producer: ()
     if (credentialsAboutToExpire(current)) {
       const newCreds = await producer();
       if (!isV3Credentials(newCreds)) {
-        throw new Error(`Plugin initially returned static V3 credentials but now returned something else: ${inspect(newCreds)}`);
+        throw new AuthenticationError(`Plugin initially returned static V3 credentials but now returned something else: ${inspect(newCreds)}`);
       }
       current = newCreds;
     }

packages/aws-cdk/lib/api/aws-auth/sdk-provider.ts

@@ -13,6 +13,7 @@ import { debug, warning } from '../../logging';
 import { traceMethods } from '../../util/tracing';
 import { Mode } from '../plugin';
 import { makeCachingProvider } from './provider-caching';
+import { AuthenticationError } from '../../toolkit/error';
 
 export type AssumeRoleAdditionalOptions = Partial<Omit<AssumeRoleCommandInput, 'ExternalId' | 'RoleArn'>>;
 
@@ -158,14 +159,14 @@ export class SdkProvider {
 
     // At this point, we need at least SOME credentials
     if (baseCreds.source === 'none') {
-      throw new Error(fmtObtainCredentialsError(env.account, baseCreds));
+      throw new AuthenticationError(fmtObtainCredentialsError(env.account, baseCreds));
     }
 
     // Simple case is if we don't need to "assumeRole" here. If so, we must now have credentials for the right
     // account.
     if (options?.assumeRoleArn === undefined) {
       if (baseCreds.source === 'incorrectDefault') {
-        throw new Error(fmtObtainCredentialsError(env.account, baseCreds));
+        throw new AuthenticationError(fmtObtainCredentialsError(env.account, baseCreds));
       }
 
       // Our current credentials must be valid and not expired. Confirm that before we get into doing
@@ -240,7 +241,7 @@ export class SdkProvider {
     const account = env.account !== UNKNOWN_ACCOUNT ? env.account : (await this.defaultAccount())?.accountId;
 
     if (!account) {
-      throw new Error(
+      throw new AuthenticationError(
         'Unable to resolve AWS account to use. It must be either configured when you define your CDK Stack, or through the environment',
       );
     }
@@ -377,7 +378,7 @@ export class SdkProvider {
       }
 
       debug(`Assuming role failed: ${err.message}`);
-      throw new Error(
+      throw new AuthenticationError(
         [
           'Could not assume role in target account',
           ...(sourceDescription ? [`using ${sourceDescription}`] : []),

packages/aws-cdk/lib/api/aws-auth/sdk.ts

@@ -319,6 +319,7 @@ import { cachedAsync } from './cached';
 import { Account } from './sdk-provider';
 import { defaultCliUserAgent } from './user-agent';
 import { debug } from '../../logging';
+import { AuthenticationError } from '../../toolkit/error';
 import { traceMethods } from '../../util/tracing';
 
 export interface S3ClientOptions {
@@ -902,7 +903,7 @@ export class SDK {
 
           return upload.done();
         } catch (e: any) {
-          throw new Error(`Upload failed: ${e.message}`);
+          throw new AuthenticationError(`Upload failed: ${e.message}`);
         }
       },
     };
@@ -957,7 +958,7 @@ export class SDK {
         const accountId = result.Account;
         const partition = result.Arn!.split(':')[1];
         if (!accountId) {
-          throw new Error("STS didn't return an account ID");
+          throw new AuthenticationError("STS didn't return an account ID");
         }
         debug('Default account ID:', accountId);
 

packages/aws-cdk/lib/api/bootstrap/bootstrap-environment.ts

@@ -6,6 +6,7 @@ import { BootstrapStack, bootstrapVersionFromTemplate } from './deploy-bootstrap
 import { legacyBootstrapTemplate } from './legacy-template';
 import { warning } from '../../logging';
 import { loadStructuredFile, serializeStructure } from '../../serialize';
+import { ToolkitError } from '../../toolkit/error';
 import { rootDir } from '../../util/directories';
 import type { SDK, SdkProvider } from '../aws-auth';
 import type { SuccessfulDeployStackResult } from '../deploy-stack';
@@ -48,16 +49,16 @@ export class Bootstrapper {
     const params = options.parameters ?? {};
 
     if (params.trustedAccounts?.length) {
-      throw new Error('--trust can only be passed for the modern bootstrap experience.');
+      throw new ToolkitError('--trust can only be passed for the modern bootstrap experience.');
     }
     if (params.cloudFormationExecutionPolicies?.length) {
-      throw new Error('--cloudformation-execution-policies can only be passed for the modern bootstrap experience.');
+      throw new ToolkitError('--cloudformation-execution-policies can only be passed for the modern bootstrap experience.');
     }
     if (params.createCustomerMasterKey !== undefined) {
-      throw new Error('--bootstrap-customer-key can only be passed for the modern bootstrap experience.');
+      throw new ToolkitError('--bootstrap-customer-key can only be passed for the modern bootstrap experience.');
     }
     if (params.qualifier) {
-      throw new Error('--qualifier can only be passed for the modern bootstrap experience.');
+      throw new ToolkitError('--qualifier can only be passed for the modern bootstrap experience.');
     }
 
     const current = await BootstrapStack.lookup(sdkProvider, environment, options.toolkitStackName);
@@ -88,7 +89,7 @@ export class Bootstrapper {
     const partition = await current.partition();
 
     if (params.createCustomerMasterKey !== undefined && params.kmsKeyId) {
-      throw new Error(
+      throw new ToolkitError(
         "You cannot pass '--bootstrap-kms-key-id' and '--bootstrap-customer-key' together. Specify one or the other",
       );
     }
@@ -131,7 +132,7 @@ export class Bootstrapper {
         `Using default execution policy of '${implicitPolicy}'. Pass '--cloudformation-execution-policies' to customize.`,
       );
     } else if (cloudFormationExecutionPolicies.length === 0) {
-      throw new Error(
+      throw new ToolkitError(
         `Please pass \'--cloudformation-execution-policies\' when using \'--trust\' to specify deployment permissions. Try a managed policy of the form \'arn:${partition}:iam::aws:policy/<PolicyName>\'.`,
       );
     } else {
@@ -226,7 +227,7 @@ export class Bootstrapper {
     );
     const policyName = arn.split('/').pop();
     if (!policyName) {
-      throw new Error('Could not retrieve the example permission boundary!');
+      throw new ToolkitError('Could not retrieve the example permission boundary!');
     }
     return Promise.resolve(policyName);
   }
@@ -308,7 +309,7 @@ export class Bootstrapper {
     if (createPolicyResponse.Policy?.Arn) {
       return createPolicyResponse.Policy.Arn;
     } else {
-      throw new Error(`Could not retrieve the example permission boundary ${arn}!`);
+      throw new ToolkitError(`Could not retrieve the example permission boundary ${arn}!`);
     }
   }
 
@@ -319,7 +320,7 @@ export class Bootstrapper {
     const regexp: RegExp = /[\w+\/=,.@-]+/;
     const matches = regexp.exec(permissionsBoundary);
     if (!(matches && matches.length === 1 && matches[0] === permissionsBoundary)) {
-      throw new Error(`The permissions boundary name ${permissionsBoundary} does not match the IAM conventions.`);
+      throw new ToolkitError(`The permissions boundary name ${permissionsBoundary} does not match the IAM conventions.`);
     }
   }
 

packages/aws-cdk/lib/api/cxapp/cloud-assembly.ts

@@ -3,6 +3,7 @@ import * as chalk from 'chalk';
 import { minimatch } from 'minimatch';
 import * as semver from 'semver';
 import { error, print, warning } from '../../logging';
+import { ToolkitError } from '../../toolkit/error';
 import { flatten } from '../../util';
 
 export enum DefaultSelection {
@@ -109,7 +110,7 @@ export class CloudAssembly {
       if (options.ignoreNoStacks) {
         return new StackCollection(this, []);
       }
-      throw new Error('This app contains no stacks');
+      throw new ToolkitError('This app contains no stacks');
     }
 
     if (allTopLevel) {
@@ -129,7 +130,7 @@ export class CloudAssembly {
     if (topLevelStacks.length > 0) {
       return this.extendStacks(topLevelStacks, stacks, extend);
     } else {
-      throw new Error('No stack found in the main cloud assembly. Use "list" to print manifest');
+      throw new ToolkitError('No stack found in the main cloud assembly. Use "list" to print manifest');
     }
   }
 
@@ -161,11 +162,11 @@ export class CloudAssembly {
         if (topLevelStacks.length === 1) {
           return new StackCollection(this, topLevelStacks);
         } else {
-          throw new Error('Since this app includes more than a single stack, specify which stacks to use (wildcards are supported) or specify `--all`\n' +
+          throw new ToolkitError('Since this app includes more than a single stack, specify which stacks to use (wildcards are supported) or specify `--all`\n' +
           `Stacks: ${stacks.map(x => x.hierarchicalId).join(' · ')}`);
         }
       default:
-        throw new Error(`invalid default behavior: ${defaultSelection}`);
+        throw new ToolkitError(`invalid default behavior: ${defaultSelection}`);
     }
   }
 
@@ -221,7 +222,7 @@ export class StackCollection {
 
   public get firstStack() {
     if (this.stackCount < 1) {
-      throw new Error('StackCollection contains no stack artifacts (trying to access the first one)');
+      throw new ToolkitError('StackCollection contains no stack artifacts (trying to access the first one)');
     }
     return this.stackArtifacts[0];
   }
@@ -270,11 +271,11 @@ export class StackCollection {
     }
 
     if (errors && !options.ignoreErrors) {
-      throw new Error('Found errors');
+      throw new ToolkitError('Found errors');
     }
 
     if (options.strict && warnings) {
-      throw new Error('Found warnings (--strict mode)');
+      throw new ToolkitError('Found warnings (--strict mode)');
     }
 
     function printMessage(logFn: (s: string) => void, prefix: string, id: string, entry: cxapi.MetadataEntry) {

packages/aws-cdk/lib/api/cxapp/cloud-executable.ts

@@ -6,6 +6,7 @@ import { CloudAssembly } from './cloud-assembly';
 import * as contextproviders from '../../context-providers';
 import { debug, warning } from '../../logging';
 import { Configuration } from '../../settings';
+import { ToolkitError } from '../../toolkit/error';
 import { SdkProvider } from '../aws-auth';
 
 /**
@@ -82,7 +83,7 @@ export class CloudExecutable {
         const missingKeys = missingContextKeys(assembly.manifest.missing);
 
         if (!this.canLookup) {
-          throw new Error(
+          throw new ToolkitError(
             'Context lookups have been disabled. '
             + 'Make sure all necessary context is already in \'cdk.context.json\' by running \'cdk synth\' on a machine with sufficient AWS credentials and committing the result. '
             + `Missing context keys: '${Array.from(missingKeys).join(', ')}'`);
@@ -214,7 +215,7 @@ function _makeCdkMetadataAvailableCondition() {
  */
 function _fnOr(operands: any[]): any {
   if (operands.length === 0) {
-    throw new Error('Cannot build `Fn::Or` with zero operands!');
+    throw new ToolkitError('Cannot build `Fn::Or` with zero operands!');
   }
   if (operands.length === 1) {
     return operands[0];

packages/aws-cdk/lib/api/cxapp/environments.ts

@@ -1,6 +1,7 @@
 import * as cxapi from '@aws-cdk/cx-api';
 import { minimatch } from 'minimatch';
 import { StackCollection } from './cloud-assembly';
+import { ToolkitError } from '../../toolkit/error';
 import { SdkProvider } from '../aws-auth';
 
 export function looksLikeGlob(environment: string) {
@@ -21,7 +22,7 @@ export async function globEnvironmentsFromStacks(stacks: StackCollection, enviro
   if (environments.length === 0) {
     const globs = JSON.stringify(environmentGlobs);
     const envList = availableEnvironments.length > 0 ? availableEnvironments.map(env => env!.name).join(', ') : '<none>';
-    throw new Error(`No environments were found when selecting across ${globs} (available: ${envList})`);
+    throw new ToolkitError(`No environments were found when selecting across ${globs} (available: ${envList})`);
   }
 
   return environments;
@@ -36,7 +37,7 @@ export function environmentsFromDescriptors(envSpecs: string[]): cxapi.Environme
   for (const spec of envSpecs) {
     const parts = spec.replace(/^aws:\/\//, '').split('/');
     if (parts.length !== 2) {
-      throw new Error(`Expected environment name in format 'aws://<account>/<region>', got: ${spec}`);
+      throw new ToolkitError(`Expected environment name in format 'aws://<account>/<region>', got: ${spec}`);
     }
 
     ret.push({

packages/aws-cdk/lib/api/cxapp/exec.ts

@@ -7,6 +7,7 @@ import * as fs from 'fs-extra';
 import * as semver from 'semver';
 import { debug, warning } from '../../logging';
 import { Configuration, PROJECT_CONFIG, USER_DEFAULTS } from '../../settings';
+import { ToolkitError } from '../../toolkit/error';
 import { loadTree, some } from '../../tree';
 import { splitBySize } from '../../util/objects';
 import { versionNumber } from '../../version';
@@ -30,7 +31,7 @@ export async function execProgram(aws: SdkProvider, config: Configuration): Prom
 
   const app = config.settings.get(['app']);
   if (!app) {
-    throw new Error(`--app is required either in command-line, in ${PROJECT_CONFIG} or in ${USER_DEFAULTS}`);
+    throw new ToolkitError(`--app is required either in command-line, in ${PROJECT_CONFIG} or in ${USER_DEFAULTS}`);
   }
 
   // bypass "synth" if app points to a cloud assembly
@@ -47,15 +48,15 @@ export async function execProgram(aws: SdkProvider, config: Configuration): Prom
 
   const outdir = config.settings.get(['output']);
   if (!outdir) {
-    throw new Error('unexpected: --output is required');
+    throw new ToolkitError('unexpected: --output is required');
   }
   if (typeof outdir !== 'string') {
-    throw new Error(`--output takes a string, got ${JSON.stringify(outdir)}`);
+    throw new ToolkitError(`--output takes a string, got ${JSON.stringify(outdir)}`);
   }
   try {
     await fs.mkdirp(outdir);
   } catch (error: any) {
-    throw new Error(`Could not create output directory ${outdir} (${error.message})`);
+    throw new ToolkitError(`Could not create output directory ${outdir} (${error.message})`);
   }
 
   debug('outdir:', outdir);
@@ -127,7 +128,7 @@ export async function execProgram(aws: SdkProvider, config: Configuration): Prom
           return ok();
         } else {
           debug('failed command:', commandAndArgs);
-          return fail(new Error(`Subprocess exited with error ${code}`));
+          return fail(new ToolkitError(`Subprocess exited with error ${code}`));
         }
       });
     });
@@ -147,7 +148,7 @@ export function createAssembly(appDir: string) {
     if (error.message.includes(cxschema.VERSION_MISMATCH)) {
       // this means the CLI version is too old.
       // we instruct the user to upgrade.
-      throw new Error(`This CDK CLI is not compatible with the CDK library used by your application. Please upgrade the CLI to the latest version.\n(${error.message})`);
+      throw new ToolkitError(`This CDK CLI is not compatible with the CDK library used by your application. Please upgrade the CLI to the latest version.\n(${error.message})`);
     }
     throw error;
   }