refactor: gate access to environment SDK behind new class (#31904)

Previously there were methods on the `Deployments` class that made it possible to directly get an SDK from the `SdkProvider` for a particular environment. Calling these methods made it possible to get an SDK without thinking of assuming roles to go into a different account.

This PR introduces a new class, `EnvironmentAccess`, with a couple of public methods that are the only ones allowed to obtain SDKs with credentials. It has the methods:

- accessStackForStackOperations(stack)
- accessStackForLookup(stack)
- accessStackForReading(stack)

These will always respect the role information on the stack.

Ideally there would have been similar methods for assets as well, but the `cdk-assets` library is entirely handling asset roles itself, and it's not in the scope of this PR to change that. That keeps on using a plain `SdkProvider`. Hotswap deployments will also just use CLI credentials and not assume role, so that also keeps on using an `SdkProvider`.

All other uses have moved to `EnvironmentAccess`.

----

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

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

@@ -1,4 +1,5 @@
 import { Tag } from '../../cdk-toolkit';
+import { StringWithoutPlaceholders } from '../util/placeholders';
 
 export const BUCKET_NAME_OUTPUT = 'BucketName';
 export const REPOSITORY_NAME_OUTPUT = 'ImageRepositoryName';
@@ -17,7 +18,7 @@ export const DEFAULT_BOOTSTRAP_VARIANT = 'AWS CDK: Default Resources';
  */
 export interface BootstrapEnvironmentOptions {
   readonly toolkitStackName?: string;
-  readonly roleArn?: string;
+  readonly roleArn?: StringWithoutPlaceholders;
   readonly parameters?: BootstrappingParameters;
   readonly force?: boolean;
 

packages/aws-cdk/lib/api/deploy-stack.ts

@@ -19,6 +19,7 @@ import { TemplateBodyParameter, makeBodyParameter } from './util/template-body-p
 import { AssetManifestBuilder } from '../util/asset-manifest-builder';
 import { determineAllowCrossAccountAssetPublishing } from './util/checks';
 import { publishAssets } from '../util/asset-publishing';
+import { StringWithoutPlaceholders } from './util/placeholders';
 
 export interface DeployStackResult {
   readonly noOp: boolean;
@@ -51,14 +52,13 @@ export interface DeployStackOptions {
   /**
    * SDK provider (seeded with default credentials)
    *
-   * Will exclusively be used to assume publishing credentials (which must
-   * start out from current credentials regardless of whether we've assumed an
-   * action role to touch the stack or not).
+   * Will be used to:
    *
-   * Used for the following purposes:
-   *
-   * - Publish legacy assets.
-   * - Upload large CloudFormation templates to the staging bucket.
+   * - Publish assets, either legacy assets or large CFN templates
+   *   that aren't themselves assets from a manifest. (Needs an SDK
+   *   Provider because the file publishing role is declared as part
+   *   of the asset).
+   * - Hotswap
    */
   readonly sdkProvider: SdkProvider;
 
@@ -70,9 +70,13 @@ export interface DeployStackOptions {
   /**
    * Role to pass to CloudFormation to execute the change set
    *
-   * @default - Role specified on stack, otherwise current
+   * To obtain a `StringWithoutPlaceholders`, run a regular
+   * string though `TargetEnvironment.replacePlaceholders`.
+   *
+   * @default - No execution role; CloudFormation either uses the role currently associated with
+   * the stack, or otherwise uses current AWS credentials.
    */
-  readonly roleArn?: string;
+  readonly roleArn?: StringWithoutPlaceholders;
 
   /**
    * Notification ARNs to pass to CloudFormation to notify when the change set has completed