Copy over generated type def file

Author: MicroFish91

api/docs/vscode-azureresources-api.d.ts

@@ -25,7 +25,7 @@ export declare namespace apiUtils {
      */
     export function getAzureExtensionApi<T extends AzureExtensionApi>(context: vscode.ExtensionContext, extensionId: string, apiVersionRange: string, options?: GetApiOptions): Promise<T>;
     /**
-     * Get extension exports for the extension with the given id. Activates extension first if needed.
+     * Activates an extension and returns its exports.
      *
      * @returns `undefined` if the extension is not installed
      */
@@ -124,19 +124,28 @@ export declare interface AzureAuthentication {
     /**
      * Gets a VS Code authentication session for an Azure subscription.
      *
-     * @param scopes - The scopes for which the authentication is needed. Use AuthenticationWwwAuthenticateRequest for supporting challenge requests.
-     * Note: use of AuthenticationWwwAuthenticateRequest requires VS Code v1.104
+     * @param scopeListOrRequest - The scopes for which the authentication is needed. Use AuthenticationWwwAuthenticateRequest for supporting challenge requests.
+     * Note: use of AuthenticationWwwAuthenticateRequest requires VS Code v1.105.0
      *
      * @returns A VS Code authentication session or undefined, if none could be obtained.
      */
-    getSessionWithScopes(scopes: string[] | vscode.AuthenticationWwwAuthenticateRequest): vscode.ProviderResult<vscode.AuthenticationSession>;
+    getSessionWithScopes(scopeListOrRequest: string[] | vscode.AuthenticationWwwAuthenticateRequest): vscode.ProviderResult<vscode.AuthenticationSession>;
 }
 
 export declare interface AzureExtensionApi {
     /**
      * The API version for this extension. It should be versioned separately from the extension and ideally remains backwards compatible.
      */
     apiVersion: string;
+    /**
+     * Optional endpoint which Azure client extensions should implement in order to receive an Azure Resources API session.
+     * See: https://github.com/microsoft/vscode-azureresourcegroups/blob/main/api/src/auth/README.md
+     *
+     * @param azureResourcesCredential - The credential to use when requesting the Azure Resources API
+     * @param clientCredential - The client verification credential initially generated by the client and passed to the Azure Resources API when requesting a new session.
+     * This credential is used to verify that the real Azure Resources extension is the one providing back the session credential.
+     */
+    receiveAzureResourcesApiSession?(azureResourcesCredential: string, clientCredential: string): void | Promise<void>;
 }
 
 /**
@@ -202,13 +211,101 @@ export declare interface AzureResourceModel extends ResourceModelBase {
     readonly viewProperties?: ViewPropertiesModel;
 }
 
+export declare interface AzureResourcesApiRequestContext {
+    clientExtensionId: string;
+    azureResourcesApiVersions: string[];
+    /**
+     * Callback invoked when Azure Resource APIs are successfully obtained through the authentication handshake.
+     *
+     * @param azureResourcesApis - Array of APIs corresponding to the requested versions. APIs are returned in the same
+     *                             order as provided in this request context. If a requested version is not
+     *                             available or does not match, `undefined` will be returned at that position.
+     */
+    onDidReceiveAzureResourcesApis: (azureResourcesApis: (AzureResourcesExtensionApi | AzureExtensionApi | undefined)[]) => void | Promise<void>;
+    /**
+     * Optional callback invoked when an error occurs during the Azure Resources API handshake process.
+     *
+     * @param error - The error that occurred during the handshake, containing an error code and message.
+     */
+    onApiRequestError?: (error: AzureResourcesApiRequestError) => void | Promise<void>;
+}
+
+export declare type AzureResourcesApiRequestError = Omit<typeof AzureResourcesApiRequestErrors[keyof typeof AzureResourcesApiRequestErrors], 'message'> & {
+    message: string;
+};
+
+/**
+ * List of errors that could occur during the authentication handshake between client extension and Azure Resources host extension.
+ */
+export declare const AzureResourcesApiRequestErrors: {
+    /**
+     * An error occurred while the client extension was creating its verification credential for the Azure Resources host extension.
+     */
+    readonly CLIENT_FAILED_CREATE_CREDENTIAL: {
+        readonly code: "ERR_CLIENT_FAILED_CREATE_CREDENTIAL";
+    };
+    /**
+     * An error occurred while the Azure Resources host extension was trying to create an API session.
+     */
+    readonly HOST_CREATE_SESSION_FAILED: {
+        readonly code: "ERR_HOST_CREATE_SESSION_FAILED";
+    };
+    /**
+     * An error occurred because the client's receiver method was provided incomplete or missing credentials.
+     */
+    readonly CLIENT_RECEIVED_INSUFFICIENT_CREDENTIALS: {
+        readonly code: "ERR_CLIENT_RECEIVED_INSUFFICIENT_CREDENTIALS";
+        readonly message: "Insufficient credentials were provided back to the client.";
+    };
+    /**
+     * The client's receiver method was provided a client credential that failed verification.
+     *
+     * This may occur when:
+     * - An untrusted extension pretends to be the Azure Resources host extension and tries to pass a fake credential
+     * - There is a faulty behavior in the client's verification process
+     */
+    readonly CLIENT_CREDENTIAL_FAILED_VERIFICATION: {
+        readonly code: "ERR_CLIENT_CREDENTIAL_FAILED_VERIFICATION";
+    };
+    /**
+     * An error occurred while asking the Azure Resources host extension to provision the specified APIs.
+     *
+     * This may occur when:
+     * - The Azure Resources extension cannot verify the issued credential that was passed back
+     * - The requesting extension is not on the Azure Resources allow list
+     * - The host extension encounters an internal error during API provisioning
+     */
+    readonly HOST_API_PROVISIONING_FAILED: {
+        readonly code: "ERR_HOST_API_PROVISIONING_FAILED";
+    };
+};
+
+export declare type AzureResourcesApiRequestPrep<T extends AzureExtensionApi> = {
+    /**
+     * The modified client extension API.  Ensures the required handshake receiver method has been added.
+     */
+    clientApi: T & Required<Pick<T, 'receiveAzureResourcesApiSession'>>;
+    /**
+     * Initiates the authentication handshake required to obtain the Azure Resources API.
+     */
+    requestResourcesApis: () => void;
+};
+
 /**
  * The current (v2) Azure Resources extension API.
  */
 export declare interface AzureResourcesExtensionApi extends AzureExtensionApi {
     resources: ResourcesApi;
 }
 
+/**
+ * The authentication layer (v4) protecting the core Azure Resources extension API.
+ */
+export declare interface AzureResourcesExtensionAuthApi extends AzureExtensionApi {
+    getAzureResourcesApi(clientExtensionId: string, azureResourcesCredential: string, azureResourcesApiVersions: string[]): Promise<(AzureExtensionApi | undefined)[]>;
+    createAzureResourcesApiSession(clientExtensionId: string, clientExtensionVersion: string, clientExtensionCredential: string): Promise<void>;
+}
+
 /**
  * Represents a type of resource as designated by Azure.
  */
@@ -300,10 +397,23 @@ export declare function getAzExtResourceType(resource: {
     kind?: string;
 }): AzExtResourceType | undefined;
 
+/**
+ * @deprecated The Azure Resources core API should be accessed through the new auth layer.
+ * See: https://github.com/microsoft/vscode-azureresourcegroups/blob/main/api/src/auth/README.md
+ * */
 export declare function getAzureResourcesExtensionApi(extensionContext: vscode.ExtensionContext, apiVersionRange: '2.0.0', options?: GetApiOptions): Promise<AzureResourcesExtensionApi>;
 
 export declare function isWrapper(maybeWrapper: unknown): maybeWrapper is Wrapper;
 
+/**
+ * Prepares a client extension for the Azure Resources authentication handshake.
+ *
+ * @param context - Prerequisite configuration and handlers to prepare the request
+ * @param clientExtensionApi - The base extension API to be modified
+ * @returns The modified client extension API (with the required receiver method added), and a method to initiate the handshake
+ */
+export declare function prepareAzureResourcesApiRequest<T extends AzureExtensionApi>(context: AzureResourcesApiRequestContext, clientExtensionApi: T): AzureResourcesApiRequestPrep<T>;
+
 /**
  * Represents the base type for all Azure and workspace resources.
  */
@@ -495,4 +605,4 @@ export declare interface Wrapper {
     unwrap<T>(): T;
 }
 
-export { };
+export { }