@aws-cdk/toolkit-lib 0.3.0 → 0.3.2

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

@@ -1202,6 +1202,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;
+}
+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