feat(iam): throw ValidationErrors instead of untyped errors (#34579)

### Issue

Relates to #32569

### Reason for this change

untyped Errors are not recommended

### Description of changes

`ValidationError`s everywhere

### Describe any new or updated permissions being added

None

### Description of how you validated changes

Existing tests. Exemptions granted as this is a refactor of existing code.

### 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*

Author: mrgrain

packages/aws-cdk-lib/.eslintrc.js

@@ -17,7 +17,6 @@ baseConfig.rules['import/no-extraneous-dependencies'] = [
 baseConfig.rules['@cdklabs/no-throw-default-error'] = ['error'];
 // not yet supported
 const noThrowDefaultErrorNotYetSupported = [
-  'aws-iam',
   'aws-secretsmanager',
   'core',
   'custom-resources',

packages/aws-cdk-lib/aws-iam/lib/grant.ts

@@ -251,7 +251,7 @@ export class Grant implements IDependable {
     }
 
     if (!addedToPrincipal.policyDependable) {
-      throw new Error('Contract violation: when Principal returns statementAdded=true, it should return a dependable');
+      throw new cdk.UnscopedValidationError('Contract violation: when Principal returns statementAdded=true, it should return a dependable');
     }
 
     return new Grant({ principalStatement: statement, options, policyDependable: addedToPrincipal.policyDependable });
@@ -372,8 +372,7 @@ export class Grant implements IDependable {
    */
   public assertSuccess(): void {
     if (!this.success) {
-      // eslint-disable-next-line max-len
-      throw new Error(`${describeGrant(this.options)} could not be added on either identity or resource policy.`);
+      throw new cdk.UnscopedValidationError(`${describeGrant(this.options)} could not be added on either identity or resource policy.`);
     }
   }
 

packages/aws-cdk-lib/aws-iam/lib/managed-policy.ts

@@ -7,7 +7,7 @@ import { AddToPrincipalPolicyResult, IGrantable, IPrincipal, PrincipalPolicyFrag
 import { undefinedIfEmpty } from './private/util';
 import { IRole } from './role';
 import { IUser } from './user';
-import { ArnFormat, Resource, Stack, Arn, Aws } from '../../core';
+import { ArnFormat, Resource, Stack, Arn, Aws, UnscopedValidationError } from '../../core';
 import { getCustomizeRolesConfig, PolicySynthesizer } from '../../core/lib/helpers-internal';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
 import { propertyInjectable } from '../../core/lib/prop-injectable';
@@ -348,7 +348,7 @@ class ManagedPolicyGrantPrincipal implements IPrincipal {
     // This property is referenced to add policy statements as a resource-based policy.
     // We should fail because a managed policy cannot be used as a principal of a policy document.
     // cf. https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#Principal_specifying
-    throw new Error(`Cannot use a ManagedPolicy '${this._managedPolicy.node.path}' as the 'Principal' or 'NotPrincipal' in an IAM Policy`);
+    throw new UnscopedValidationError(`Cannot use a ManagedPolicy '${this._managedPolicy.node.path}' as the 'Principal' or 'NotPrincipal' in an IAM Policy`);
   }
 
   public addToPolicy(statement: PolicyStatement): boolean {

packages/aws-cdk-lib/aws-iam/lib/policy-document.ts

@@ -55,7 +55,7 @@ export class PolicyDocument implements cdk.IResolvable {
     const newPolicyDocument = new PolicyDocument();
     const statement = obj.Statement ?? [];
     if (statement && !Array.isArray(statement)) {
-      throw new Error('Statement must be an array');
+      throw new cdk.UnscopedValidationError('Statement must be an array');
     }
     newPolicyDocument.addStatements(...obj.Statement.map((s: any) => PolicyStatement.fromJson(s)));
     return newPolicyDocument;

packages/aws-cdk-lib/aws-iam/lib/policy-statement.ts

@@ -7,16 +7,17 @@ import {
 import { normalizeStatement } from './private/postprocess-policy-document';
 import { LITERAL_STRING_KEY, mergePrincipal, sum } from './private/util';
 import * as cdk from '../../core';
+import { UnscopedValidationError } from '../../core';
 
 const ensureArrayOrUndefined = (field: any) => {
   if (field === undefined) {
     return undefined;
   }
   if (typeof (field) !== 'string' && !Array.isArray(field)) {
-    throw new Error('Fields must be either a string or an array of strings');
+    throw new UnscopedValidationError('Fields must be either a string or an array of strings');
   }
   if (Array.isArray(field) && !!field.find((f: any) => typeof (f) !== 'string')) {
-    throw new Error('Fields must be either a string or an array of strings');
+    throw new UnscopedValidationError('Fields must be either a string or an array of strings');
   }
   return Array.isArray(field) ? field : [field];
 };
@@ -67,7 +68,7 @@ export class PolicyStatement {
     // validate that the PolicyStatement has the correct shape
     const errors = ret.validateForAnyPolicy();
     if (errors.length > 0) {
-      throw new Error('Incorrect Policy Statement: ' + errors.join('\n'));
+      throw new UnscopedValidationError('Incorrect Policy Statement: ' + errors.join('\n'));
     }
 
     return ret;
@@ -148,7 +149,7 @@ export class PolicyStatement {
   public addActions(...actions: string[]) {
     this.assertNotFrozen('addActions');
     if (actions.length > 0 && this._notAction.length > 0) {
-      throw new Error('Cannot add \'Actions\' to policy statement if \'NotActions\' have been added');
+      throw new UnscopedValidationError('Cannot add \'Actions\' to policy statement if \'NotActions\' have been added');
     }
     this.validatePolicyActions(actions);
     this._action.push(...actions);
@@ -165,7 +166,7 @@ export class PolicyStatement {
   public addNotActions(...notActions: string[]) {
     this.assertNotFrozen('addNotActions');
     if (notActions.length > 0 && this._action.length > 0) {
-      throw new Error('Cannot add \'NotActions\' to policy statement if \'Actions\' have been added');
+      throw new UnscopedValidationError('Cannot add \'NotActions\' to policy statement if \'Actions\' have been added');
     }
     this.validatePolicyActions(notActions);
     this._notAction.push(...notActions);
@@ -192,7 +193,7 @@ export class PolicyStatement {
   public addPrincipals(...principals: IPrincipal[]) {
     this.assertNotFrozen('addPrincipals');
     if (principals.length > 0 && this._notPrincipals.length > 0) {
-      throw new Error('Cannot add \'Principals\' to policy statement if \'NotPrincipals\' have been added');
+      throw new UnscopedValidationError('Cannot add \'Principals\' to policy statement if \'NotPrincipals\' have been added');
     }
     for (const principal of principals) {
       this.validatePolicyPrincipal(principal);
@@ -217,7 +218,7 @@ export class PolicyStatement {
   public addNotPrincipals(...notPrincipals: IPrincipal[]) {
     this.assertNotFrozen('addNotPrincipals');
     if (notPrincipals.length > 0 && this._principals.length > 0) {
-      throw new Error('Cannot add \'NotPrincipals\' to policy statement if \'Principals\' have been added');
+      throw new UnscopedValidationError('Cannot add \'NotPrincipals\' to policy statement if \'Principals\' have been added');
     }
     for (const notPrincipal of notPrincipals) {
       this.validatePolicyPrincipal(notPrincipal);
@@ -236,14 +237,14 @@ export class PolicyStatement {
     if (cdk.Token.isUnresolved(actions)) return;
     for (const action of actions || []) {
       if (!cdk.Token.isUnresolved(action) && !/^(\*|[a-zA-Z0-9-]+:[a-zA-Z0-9*]+)$/.test(action)) {
-        throw new Error(`Action '${action}' is invalid. An action string consists of a service namespace, a colon, and the name of an action. Action names can include wildcards.`);
+        throw new UnscopedValidationError(`Action '${action}' is invalid. An action string consists of a service namespace, a colon, and the name of an action. Action names can include wildcards.`);
       }
     }
   }
 
   private validatePolicyPrincipal(principal: IPrincipal) {
     if (principal instanceof Group) {
-      throw new Error('Cannot use an IAM Group as the \'Principal\' or \'NotPrincipal\' in an IAM Policy');
+      throw new UnscopedValidationError('Cannot use an IAM Group as the \'Principal\' or \'NotPrincipal\' in an IAM Policy');
     }
   }
 
@@ -323,7 +324,7 @@ export class PolicyStatement {
   public addResources(...arns: string[]) {
     this.assertNotFrozen('addResources');
     if (arns.length > 0 && this._notResource.length > 0) {
-      throw new Error('Cannot add \'Resources\' to policy statement if \'NotResources\' have been added');
+      throw new UnscopedValidationError('Cannot add \'Resources\' to policy statement if \'NotResources\' have been added');
     }
     this._resource.push(...arns);
   }
@@ -339,7 +340,7 @@ export class PolicyStatement {
   public addNotResources(...arns: string[]) {
     this.assertNotFrozen('addNotResources');
     if (arns.length > 0 && this._resource.length > 0) {
-      throw new Error('Cannot add \'NotResources\' to policy statement if \'Resources\' have been added');
+      throw new UnscopedValidationError('Cannot add \'NotResources\' to policy statement if \'Resources\' have been added');
     }
     this._notResource.push(...arns);
   }
@@ -517,7 +518,7 @@ export class PolicyStatement {
       this.principalConditionsJson = theseConditions;
     } else {
       if (this.principalConditionsJson !== theseConditions) {
-        throw new Error(`All principals in a PolicyStatement must have the same Conditions (got '${this.principalConditionsJson}' and '${theseConditions}'). Use multiple statements instead.`);
+        throw new UnscopedValidationError(`All principals in a PolicyStatement must have the same Conditions (got '${this.principalConditionsJson}' and '${theseConditions}'). Use multiple statements instead.`);
       }
     }
     this.addConditions(conditions);
@@ -676,7 +677,7 @@ export class PolicyStatement {
    */
   private assertNotFrozen(method: string) {
     if (this._frozen) {
-      throw new Error(`${method}: freeze() has been called on this PolicyStatement previously, so it can no longer be modified`);
+      throw new UnscopedValidationError(`${method}: freeze() has been called on this PolicyStatement previously, so it can no longer be modified`);
     }
   }
 }
@@ -810,7 +811,7 @@ class JsonPrincipal extends PrincipalBase {
       json = { [LITERAL_STRING_KEY]: [json] };
     }
     if (typeof(json) !== 'object') {
-      throw new Error(`JSON IAM principal should be an object, got ${JSON.stringify(json)}`);
+      throw new UnscopedValidationError(`JSON IAM principal should be an object, got ${JSON.stringify(json)}`);
     }
 
     this.policyFragment = {
@@ -853,7 +854,7 @@ export function deriveEstimateSizeOptions(scope: IConstruct): EstimateSizeOption
   const actionEstimate = 20;
   const arnEstimate = scope.node.tryGetContext(ARN_SIZE_ESTIMATE_CONTEXT_KEY) ?? DEFAULT_ARN_SIZE_ESTIMATE;
   if (typeof arnEstimate !== 'number') {
-    throw new Error(`Context value ${ARN_SIZE_ESTIMATE_CONTEXT_KEY} should be a number, got ${JSON.stringify(arnEstimate)}`);
+    throw new UnscopedValidationError(`Context value ${ARN_SIZE_ESTIMATE_CONTEXT_KEY} should be a number, got ${JSON.stringify(arnEstimate)}`);
   }
 
   return { actionEstimate, arnEstimate };

packages/aws-cdk-lib/aws-iam/lib/policy.ts

@@ -7,7 +7,7 @@ import { AddToPrincipalPolicyResult, IGrantable, IPrincipal, PrincipalPolicyFrag
 import { generatePolicyName, undefinedIfEmpty } from './private/util';
 import { IRole } from './role';
 import { IUser } from './user';
-import { IResource, Lazy, Resource } from '../../core';
+import { IResource, Lazy, Resource, UnscopedValidationError } from '../../core';
 import { addConstructMetadata, MethodMetadata } from '../../core/lib/metadata-resource';
 import { propertyInjectable } from '../../core/lib/prop-injectable';
 
@@ -294,7 +294,7 @@ class PolicyGrantPrincipal implements IPrincipal {
     // This property is referenced to add policy statements as a resource-based policy.
     // We should fail because a policy cannot be used as a principal of a policy document.
     // cf. https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html#Principal_specifying
-    throw new Error(`Cannot use a Policy '${this._policy.node.path}' as the 'Principal' or 'NotPrincipal' in an IAM Policy`);
+    throw new UnscopedValidationError(`Cannot use a Policy '${this._policy.node.path}' as the 'Principal' or 'NotPrincipal' in an IAM Policy`);
   }
 
   public addToPolicy(statement: PolicyStatement): boolean {

packages/aws-cdk-lib/aws-iam/lib/principals.ts

@@ -6,6 +6,7 @@ import { defaultAddPrincipalToAssumeRole } from './private/assume-role-policy';
 import { LITERAL_STRING_KEY, mergePrincipal } from './private/util';
 import { ISamlProvider } from './saml-provider';
 import * as cdk from '../../core';
+import { UnscopedValidationError } from '../../core';
 import { RegionInfo } from '../../region-info';
 
 /**
@@ -354,7 +355,7 @@ export class PrincipalWithConditions extends PrincipalAdapter {
       // if either the existing condition or the new one contain unresolved
       // tokens, fail the merge. this is as far as we go at this point.
       if (cdk.Token.isUnresolved(condition) || cdk.Token.isUnresolved(existing)) {
-        throw new Error(`multiple "${operator}" conditions cannot be merged if one of them contains an unresolved token`);
+        throw new UnscopedValidationError(`multiple "${operator}" conditions cannot be merged if one of them contains an unresolved token`);
       }
 
       validateConditionObject(existing);
@@ -479,7 +480,7 @@ export class AccountPrincipal extends ArnPrincipal {
   constructor(public readonly accountId: any) {
     super(new StackDependentToken(stack => `arn:${stack.partition}:iam::${accountId}:root`).toString());
     if (!cdk.Token.isUnresolved(accountId) && typeof accountId !== 'string') {
-      throw new Error('accountId should be of type string');
+      throw new UnscopedValidationError('accountId should be of type string');
     }
     this.principalAccount = accountId;
   }
@@ -617,7 +618,7 @@ export class OrganizationPrincipal extends PrincipalBase {
     // We can only validate if it's a literal string (not a token)
     if (!cdk.Token.isUnresolved(organizationId)) {
       if (!organizationId.match(/^o-[a-z0-9]{10,32}$/)) {
-        throw new Error(`Expected Organization ID must match regex pattern ^o-[a-z0-9]{10,32}$, received ${organizationId}`);
+        throw new UnscopedValidationError(`Expected Organization ID must match regex pattern ^o-[a-z0-9]{10,32}$, received ${organizationId}`);
       }
     }
   }
@@ -874,7 +875,7 @@ export class CompositePrincipal extends PrincipalBase {
   constructor(...principals: IPrincipal[]) {
     super();
     if (principals.length === 0) {
-      throw new Error('CompositePrincipals must be constructed with at least 1 Principal but none were passed.');
+      throw new UnscopedValidationError('CompositePrincipals must be constructed with at least 1 Principal but none were passed.');
     }
     this.assumeRoleAction = principals[0].assumeRoleAction;
     this.addPrincipals(...principals);
@@ -903,7 +904,7 @@ export class CompositePrincipal extends PrincipalBase {
     for (const p of this._principals) {
       const fragment = p.policyFragment;
       if (fragment.conditions && Object.keys(fragment.conditions).length > 0) {
-        throw new Error(
+        throw new UnscopedValidationError(
           'Components of a CompositePrincipal must not have conditions. ' +
           `Tried to add the following fragment: ${JSON.stringify(fragment)}`);
       }
@@ -1022,6 +1023,6 @@ class ServicePrincipalToken implements cdk.IResolvable {
  */
 export function validateConditionObject(x: unknown): asserts x is Record<string, unknown> {
   if (!x || typeof x !== 'object' || Array.isArray(x)) {
-    throw new Error('A Condition should be represented as a map of operator to value');
+    throw new UnscopedValidationError('A Condition should be represented as a map of operator to value');
   }
 }

packages/aws-cdk-lib/aws-iam/lib/private/util.ts

@@ -1,5 +1,5 @@
 import { IConstruct } from 'constructs';
-import { captureStackTrace, DefaultTokenResolver, IPostProcessor, IResolvable, IResolveContext, Lazy, StringConcat, Token, Tokenization } from '../../../core';
+import { captureStackTrace, DefaultTokenResolver, IPostProcessor, IResolvable, IResolveContext, Lazy, StringConcat, Token, Tokenization, UnscopedValidationError, ValidationError } from '../../../core';
 import { IPolicy } from '../policy';
 
 export const MAX_POLICY_NAME_LEN = 128;
@@ -60,7 +60,7 @@ export class AttachedPolicies {
     }
 
     if (this.policies.find(p => p.policyName === policy.policyName)) {
-      throw new Error(`A policy named "${policy.policyName}" is already attached`);
+      throw new ValidationError(`A policy named "${policy.policyName}" is already attached`, policy);
     }
 
     this.policies.push(policy);
@@ -79,7 +79,7 @@ export function mergePrincipal(target: { [key: string]: string[] }, source: { [k
 
   if ((LITERAL_STRING_KEY in source && targetKeys.some(k => k !== LITERAL_STRING_KEY)) ||
     (LITERAL_STRING_KEY in target && sourceKeys.some(k => k !== LITERAL_STRING_KEY))) {
-    throw new Error(`Cannot merge principals ${JSON.stringify(target)} and ${JSON.stringify(source)}; if one uses a literal principal string the other one must be empty`);
+    throw new UnscopedValidationError(`Cannot merge principals ${JSON.stringify(target)} and ${JSON.stringify(source)}; if one uses a literal principal string the other one must be empty`);
   }
 
   for (const key of sourceKeys) {