@aws-cdk/toolkit-lib 0.3.1 → 0.3.3

package/lib/api/shared-public.d.ts

@@ -1021,7 +1021,10 @@ export declare class AssemblyError extends ToolkitError {
 	readonly stacks?: cxapi.CloudFormationStackArtifact[];
 	private constructor();
 }
-declare class ContextProviderError extends ToolkitError {
+/**
+ * Represents an error originating from a Context Provider
+ */
+export declare class ContextProviderError extends ToolkitError {
 	/**
 	 * Denotes the source of the error as user.
 	 */
@@ -1109,6 +1112,19 @@ export interface StackSelector {
 	 */
 	failOnEmpty?: boolean;
 }
+/**
+ * Metadata entry for a resource within a CloudFormation stack
+ */
+export interface ResourceMetadata {
+	/**
+	 * The resource's metadata as declared in the cloud assembly
+	 */
+	readonly entry: MetadataEntry;
+	/**
+	 * The construct path of the resource
+	 */
+	readonly constructPath: string;
+}
 /**
  * The current action being performed by the CLI. 'none' represents the absence of an action.
  */
@@ -1202,6 +1218,168 @@ export interface IIoHost {
 	 */
 	requestResponse<T, U>(msg: IoRequest<T, U>): Promise<U>;
 }
+type ForReading = 0;
+type ForWriting = 1;
+interface CredentialProviderSource {
+	name: string;
+	/**
+	 * Whether the credential provider is even online
+	 *
+	 * Guaranteed to be called before any of the other functions are called.
+	 */
+	isAvailable(): Promise<boolean>;
+	/**
+	 * Whether the credential provider can provide credentials for the given account.
+	 */
+	canProvideCredentials(accountId: string): Promise<boolean>;
+	/**
+	 * Construct a credential provider for the given account and the given access mode
+	 *
+	 * Guaranteed to be called only if canProvideCredentials() returned true at some point.
+	 *
+	 * While it is possible for the plugin to return a static set of credentials, it is
+	 * recommended to return a provider.
+	 */
+	getProvider(accountId: string, mode: ForReading | ForWriting, options?: PluginProviderOptions): Promise<PluginProviderResult>;
+}
+interface IPluginHost {
+	/**
+	 * Registers a credential provider source. If, in the authentication process,
+	 * the CLI decides to try credentials from the plugins, it will go through the
+	 * sources registered in this way, in the same order as they were registered.
+	 */
+	registerCredentialProviderSource(source: CredentialProviderSource): void;
+}
+interface PluginProviderOptions {
+	/**
+	 * Whether or not this implementation of the CLI will recognize the `SDKv3CompatibleCredentialProvider` return variant
+	 *
+	 * Unless otherwise indicated, the CLI version will only support SDKv3
+	 * credentials, not SDKv3 providers. You should avoid returning types that the
+	 * consuming CLI will not understand, because it will most likely crash.
+	 *
+	 * @default false
+	 */
+	readonly supportsV3Providers?: boolean;
+}
+type PluginProviderResult = SDKv2CompatibleCredentials | SDKv3CompatibleCredentialProvider | SDKv3CompatibleCredentials;
+interface SDKv2CompatibleCredentials {
+	/**
+	 * AWS access key ID.
+	 */
+	accessKeyId: string;
+	/**
+	 * Time when credentials should be considered expired.
+	 * Used in conjunction with expired.
+	 */
+	expireTime?: Date | null;
+	/**
+	 * AWS secret access key.
+	 */
+	secretAccessKey: string;
+	/**
+	 * AWS session token.
+	 */
+	sessionToken?: string;
+	/**
+	 * Gets the existing credentials, refreshing them if necessary, and returns
+	 * a promise that will be fulfilled immediately (if no refresh is necessary)
+	 * or when the refresh has completed.
+	 */
+	getPromise(): Promise<void>;
+}
+type SDKv3CompatibleCredentialProvider = (identityProperties?: Record<string, any>) => Promise<SDKv3CompatibleCredentials>;
+interface SDKv3CompatibleCredentials {
+	/**
+	 * AWS access key ID
+	 */
+	readonly accessKeyId: string;
+	/**
+	 * AWS secret access key
+	 */
+	readonly secretAccessKey: string;
+	/**
+	 * A security or session token to use with these credentials. Usually
+	 * present for temporary credentials.
+	 */
+	readonly sessionToken?: string;
+	/**
+	 * A `Date` when the identity or credential will no longer be accepted.
+	 */
+	readonly expiration?: Date;
+}
+export interface ContextProviderPlugin {
+	getValue(args: {
+		[key: string]: any;
+	}): Promise<any>;
+}
+/**
+ * Class to manage a plugin collection
+ *
+ * It provides a `load()` function that loads a JavaScript
+ * module from disk, and gives it access to the `IPluginHost` interface
+ * to register itself.
+ */
+export declare class PluginHost implements IPluginHost {
+	/**
+	 * Access the currently registered CredentialProviderSources. New sources can
+	 * be registered using the +registerCredentialProviderSource+ method.
+	 */
+	readonly credentialProviderSources: CredentialProviderSource[];
+	readonly contextProviderPlugins: Record<string, ContextProviderPlugin>;
+	ioHost?: IIoHost;
+	private readonly alreadyLoaded;
+	/**
+	 * Loads a plug-in into this PluginHost.
+	 *
+	 * Will use `require.resolve()` to get the most accurate representation of what
+	 * code will get loaded in error messages. As such, it will not work in
+	 * unit tests with Jest virtual modules becauase of <https://github.com/jestjs/jest/issues/9543>.
+	 *
+	 * @param moduleSpec the specification (path or name) of the plug-in module to be loaded.
+	 * @param ioHost the I/O host to use for printing progress information
+	 */
+	load(moduleSpec: string, ioHost?: IIoHost): void;
+	/**
+	 * Allows plug-ins to register new CredentialProviderSources.
+	 *
+	 * @param source a new CredentialProviderSource to register.
+	 */
+	registerCredentialProviderSource(source: CredentialProviderSource): void;
+	/**
+	 * (EXPERIMENTAL) Allow plugins to register context providers
+	 *
+	 * Context providers are objects with the following method:
+	 *
+	 * ```ts
+	 *   getValue(args: {[key: string]: any}): Promise<any>;
+	 * ```
+	 *
+	 * Currently, they cannot reuse the CDK's authentication mechanisms, so they
+	 * must be prepared to either not make AWS calls or use their own source of
+	 * AWS credentials.
+	 *
+	 * This feature is experimental, and only intended to be used internally at Amazon
+	 * as a trial.
+	 *
+	 * After registering with 'my-plugin-name', the provider must be addressed as follows:
+	 *
+	 * ```ts
+	 * const value = ContextProvider.getValue(this, {
+	 *   providerName: 'plugin',
+	 *   props: {
+	 *     pluginName: 'my-plugin-name',
+	 *     myParameter1: 'xyz',
+	 *   },
+	 *   includeEnvironment: true | false,
+	 *   dummyValue: 'what-to-return-on-the-first-pass',
+	 * })
+	 * ```
+	 *
+	 * @experimental
+	 */
+	registerContextProviderAlpha(pluginProviderName: string, provider: ContextProviderPlugin): void;
+}
 export interface BootstrapEnvironmentProgress {
 	/**
 	 * The total number of environments being deployed
@@ -1438,32 +1616,6 @@ export interface DeployConfirmationRequest extends ConfirmationRequest {
 	 */
 	readonly permissionChangeType: PermissionChangeType;
 }
-export interface StackDeployProgress {
-	/**
-	 * The total number of stacks being deployed
-	 */
-	readonly total: number;
-	/**
-	 * The count of the stack currently attempted to be deployed
-	 *
-	 * This is counting value, not an identifier.
-	 */
-	readonly current: number;
-	/**
-	 * The stack that's currently being deployed
-	 */
-	readonly stack: CloudFormationStackArtifact;
-}
-/**
- * Payload for a yes/no confirmation in deploy. Includes information on
- * what kind of change is being made.
- */
-export interface DeployConfirmationRequest extends ConfirmationRequest {
-	/**
-	 * The type of change being made to the IAM permissions.
-	 */
-	readonly permissionChangeType: PermissionChangeType;
-}
 export interface BuildAsset {
 	/**
 	 * The asset that is build
@@ -1576,16 +1728,6 @@ export interface StackProgress {
 	 */
 	readonly formatted: string;
 }
-interface ResourceMetadata {
-	/**
-	 * The resource's metadata as declared in the cloud assembly
-	 */
-	readonly entry: MetadataEntry;
-	/**
-	 * The construct path of the resource
-	 */
-	readonly constructPath: string;
-}
 /**
  * Payload when stack monitoring is starting or stopping for a given stack deployment.
  */