@microsoft/teamsfx 1.1.2-alpha.7eddd6cf4.0 → 1.1.2-alpha.9bd0cb559.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/teamsfx",
-  "version": "1.1.2-alpha.7eddd6cf4.0",
+  "version": "1.1.2-alpha.9bd0cb559.0",
   "description": "Microsoft Teams Framework for Node.js and browser.",
   "main": "dist/index.node.cjs.js",
   "browser": "dist/index.esm2017.js",
@@ -49,7 +49,7 @@
     "@azure/identity": "^2.0.1",
     "@azure/msal-browser": "^2.21.0",
     "@azure/msal-node": "~1.1.0",
-    "@microsoft/adaptivecards-tools": "1.0.2-alpha.7eddd6cf4.0",
+    "@microsoft/adaptivecards-tools": "1.0.2-alpha.9bd0cb559.0",
     "@microsoft/microsoft-graph-client": "^3.0.1",
     "adaptivecards": "^2.10.0",
     "axios": "^0.27.2",
@@ -129,7 +129,7 @@
     "webpack": "^5.62.1",
     "yargs": "^17.2.1"
   },
-  "gitHead": "da6cb4205966b5bd0ab17122f498f2bdd52f33f4",
+  "gitHead": "3af4b6e0aa2b7bcfbf2dbbf1fccbe4a03ea8a71b",
   "publishConfig": {
     "access": "public"
   },

package/types/teamsfx.d.ts

@@ -1,8 +1,7 @@
 /// <reference types="node" />
 
 import { AccessToken } from '@azure/identity';
-import { Activity } from 'botbuilder-core';
-import { Activity as Activity_2 } from 'botbuilder';
+import { Activity } from 'botbuilder';
 import { Attachment } from 'botbuilder';
 import { AuthenticationProvider } from '@microsoft/microsoft-graph-client';
 import { AxiosInstance } from 'axios';
@@ -12,26 +11,31 @@ import { CardAction } from 'botbuilder';
 import { CardImage } from 'botbuilder';
 import { ChannelInfo } from 'botbuilder';
 import { Client } from '@microsoft/microsoft-graph-client';
+import { ComponentDialog } from 'botbuilder-dialogs';
 import { ConnectionConfig } from 'tedious';
 import { ConversationReference } from 'botbuilder';
+import { ConversationState } from 'botbuilder';
 import { Dialog } from 'botbuilder-dialogs';
 import { DialogContext } from 'botbuilder-dialogs';
 import { DialogTurnResult } from 'botbuilder-dialogs';
 import { GetTokenOptions } from '@azure/identity';
 import { HeroCard } from 'botbuilder';
 import { IAdaptiveCard } from 'adaptivecards';
-import { InvokeResponse } from 'botbuilder-core';
-import { InvokeResponse as InvokeResponse_2 } from 'botbuilder';
+import { InvokeResponse } from 'botbuilder';
 import { O365ConnectorCard } from 'botbuilder';
 import { ReceiptCard } from 'botbuilder';
 import { SecureContextOptions } from 'tls';
+import { SigninStateVerificationQuery } from 'botbuilder';
+import { StatePropertyAccessor } from 'botbuilder';
 import { StatusCodes } from 'botbuilder';
+import { Storage as Storage_2 } from 'botbuilder';
+import { TeamsActivityHandler } from 'botbuilder';
 import { TeamsChannelAccount } from 'botbuilder';
 import { ThumbnailCard } from 'botbuilder';
 import { TokenCredential } from '@azure/identity';
 import { TokenResponse } from 'botframework-schema';
-import { TurnContext } from 'botbuilder-core';
-import { TurnContext as TurnContext_2 } from 'botbuilder';
+import { TurnContext } from 'botbuilder';
+import { UserState } from 'botbuilder';
 import { WebRequest } from 'botbuilder';
 import { WebResponse } from 'botbuilder';
 
@@ -271,6 +275,176 @@ export declare class BearerTokenAuthProvider implements AuthProvider {
     AddAuthenticationInfo(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
 }
 
+/**
+ * Interface for SSO configuration for Bot SSO
+ */
+export declare interface BotSsoConfig {
+    /**
+     * aad related configurations
+     */
+    aad: {
+        /**
+         * The list of scopes for which the token will have access
+         */
+        scopes: string[];
+    } & AuthenticationConfiguration;
+    dialog?: {
+        /**
+         * Custom sso execution activity handler class which should implement the interface {@link BotSsoExecutionActivityHandler}. If not provided, it will use {@link DefaultBotSsoExecutionActivityHandler} by default
+         */
+        CustomBotSsoExecutionActivityHandler?: new (ssoConfig: BotSsoConfig) => BotSsoExecutionActivityHandler;
+        /**
+         * Conversation state for sso command bot, if not provided, it will use internal memory storage to create a new one.
+         */
+        conversationState?: ConversationState;
+        /**
+         * User state for sso command bot, if not provided, it will use internal memory storage to create a new one.
+         */
+        userState?: UserState;
+        /**
+         * Used by {@link BotSsoExecutionDialog} to remove duplicated messages, if not provided, it will use internal memory storage
+         */
+        dedupStorage?: Storage_2;
+        /**
+         * Settings used to configure an teams sso prompt dialog.
+         */
+        ssoPromptConfig?: {
+            /**
+             * Number of milliseconds the prompt will wait for the user to authenticate.
+             * Defaults to a value `900,000` (15 minutes.)
+             */
+            timeout?: number;
+            /**
+             * Value indicating whether the TeamsBotSsoPrompt should end upon receiving an
+             * invalid message.  Generally the TeamsBotSsoPrompt will end the auth flow when receives user
+             * message not related to the auth flow. Setting the flag to false ignores the user's message instead.
+             * Defaults to value `true`
+             */
+            endOnInvalidMessage?: boolean;
+        };
+    };
+}
+
+/**
+ * Interface for user to customize SSO execution activity handler
+ *
+ * @remarks
+ * Bot SSO execution activity handler is to handle SSO login process and trigger SSO command using {@link BotSsoExecutionDialog}.
+ * You can use this interface to implement your own SSO execution dialog, and pass it to ConversationBot options:
+ *
+ * ```typescript
+ * export const commandBot = new ConversationBot({
+ *   ...
+ *   ssoConfig: {
+ *     ...
+ *     dialog: {
+ *       CustomBotSsoExecutionActivityHandler: YourCustomBotSsoExecutionActivityHandler,
+ *     }
+ *   },
+ *    ...
+ * });
+ * ```
+ * For details information about how to implement a BotSsoExecutionActivityHandler, please refer {@link DefaultBotSsoExecutionActivityHandler} class source code.
+ */
+export declare interface BotSsoExecutionActivityHandler {
+    /**
+     * Add {@link TeamsFxBotSsoCommandHandler} instance to {@link BotSsoExecutionDialog}
+     * @param handler {@link BotSsoExecutionDialogHandler} callback function
+     * @param triggerPatterns The trigger pattern
+     *
+     * @remarks
+     * This function is used to add SSO command to {@link BotSsoExecutionDialog} instance.
+     */
+    addCommand(handler: BotSsoExecutionDialogHandler, triggerPatterns: TriggerPatterns): void;
+    /**
+     * Called to initiate the event emission process.
+     * @param context The context object for the current turn.
+     */
+    run(context: TurnContext): Promise<void>;
+    /**
+     * Receives invoke activities with Activity name of 'signin/verifyState'.
+     * @param context A context object for this turn.
+     * @param query Signin state (part of signin action auth flow) verification invoke query.
+     * @returns A promise that represents the work queued.
+     *
+     * @remarks
+     * It should trigger {@link BotSsoExecutionDialog} instance to handle signin process
+     */
+    handleTeamsSigninVerifyState(context: TurnContext, query: SigninStateVerificationQuery): Promise<void>;
+    /**
+     * Receives invoke activities with Activity name of 'signin/tokenExchange'
+     * @param context A context object for this turn.
+     * @param query Signin state (part of signin action auth flow) verification invoke query
+     * @returns A promise that represents the work queued.
+     *
+     * @remark
+     * It should trigger {@link BotSsoExecutionDialog} instance to handle signin process
+     */
+    handleTeamsSigninTokenExchange(context: TurnContext, query: SigninStateVerificationQuery): Promise<void>;
+}
+
+/**
+ * Sso execution dialog, use to handle sso command
+ */
+export declare class BotSsoExecutionDialog extends ComponentDialog {
+    private dedupStorage;
+    private dedupStorageKeys;
+    private commandMapping;
+    /**
+     * Creates a new instance of the BotSsoExecutionDialog.
+     * @param dedupStorage Helper storage to remove duplicated messages
+     * @param settings The list of scopes for which the token will have access
+     * @param teamsfx {@link TeamsFx} instance for authentication
+     */
+    constructor(dedupStorage: Storage_2, ssoPromptSettings: TeamsBotSsoPromptSettings, teamsfx: TeamsFx, dialogName?: string);
+    /**
+     * Add TeamsFxBotSsoCommandHandler instance
+     * @param handler {@link BotSsoExecutionDialogHandler} callback function
+     * @param triggerPatterns The trigger pattern
+     */
+    addCommand(handler: BotSsoExecutionDialogHandler, triggerPatterns: TriggerPatterns): void;
+    private getCommandHash;
+    /**
+     * The run method handles the incoming activity (in the form of a DialogContext) and passes it through the dialog system.
+     *
+     * @param context The context object for the current turn.
+     * @param accessor The instance of StatePropertyAccessor for dialog system.
+     */
+    run(context: TurnContext, accessor: StatePropertyAccessor): Promise<void>;
+    private getActivityText;
+    private commandRouteStep;
+    private ssoStep;
+    private dedupStep;
+    /**
+     * Called when the component is ending.
+     *
+     * @param context Context for the current turn of conversation.
+     */
+    protected onEndDialog(context: TurnContext): Promise<void>;
+    /**
+     * If a user is signed into multiple Teams clients, the Bot might receive a "signin/tokenExchange" from each client.
+     * Each token exchange request for a specific user login will have an identical activity.value.Id.
+     * Only one of these token exchange requests should be processed by the bot. For a distributed bot in production,
+     * this requires a distributed storage to ensure only one token exchange is processed.
+     * @param context Context for the current turn of conversation.
+     * @returns boolean value indicate whether the message should be removed
+     */
+    private shouldDedup;
+    private getStorageKey;
+    private matchPattern;
+    private isPatternMatched;
+    private getMatchesCommandId;
+    /**
+     * Ensure bot is running in MS Teams since TeamsBotSsoPrompt is only supported in MS Teams channel.
+     * @param dc dialog context
+     * @throws {@link ErrorCode|ChannelNotSupported} if bot channel is not MS Teams
+     * @internal
+     */
+    private ensureMsTeamsChannel;
+}
+
+export declare type BotSsoExecutionDialogHandler = (context: TurnContext, tokenResponse: TeamsBotSsoPromptTokenResponse, message: CommandMessage) => Promise<void>;
+
 /**
  * A card action bot to respond to adaptive card universal actions.
  */
@@ -389,25 +563,39 @@ export declare class Channel implements NotificationTarget {
 export declare class CommandBot {
     private readonly adapter;
     private readonly middleware;
+    private readonly ssoConfig;
     /**
      * Creates a new instance of the `CommandBot`.
      *
      * @param adapter The bound `BotFrameworkAdapter`.
      * @param options - initialize options
      */
-    constructor(adapter: BotFrameworkAdapter, options?: CommandOptions);
+    constructor(adapter: BotFrameworkAdapter, options?: CommandOptions, ssoCommandActivityHandler?: BotSsoExecutionActivityHandler, ssoConfig?: BotSsoConfig);
     /**
      * Registers a command into the command bot.
      *
-     * @param command The command to registered.
+     * @param command The command to register.
      */
     registerCommand(command: TeamsFxBotCommandHandler): void;
     /**
      * Registers commands into the command bot.
      *
-     * @param commands The command to registered.
+     * @param commands The commands to register.
      */
     registerCommands(commands: TeamsFxBotCommandHandler[]): void;
+    /**
+     * Registers a sso command into the command bot.
+     *
+     * @param command The command to register.
+     */
+    registerSsoCommand(ssoCommand: TeamsFxBotSsoCommandHandler): void;
+    /**
+     * Registers commands into the command bot.
+     *
+     * @param commands The commands to register.
+     */
+    registerSsoCommands(ssoCommands: TeamsFxBotSsoCommandHandler[]): void;
+    private validateSsoActivityHandler;
 }
 
 /**
@@ -432,6 +620,10 @@ export declare interface CommandOptions {
      * The commands to registered with the command bot. Each command should implement the interface {@link TeamsFxBotCommandHandler} so that it can be correctly handled by this command bot.
      */
     commands?: TeamsFxBotCommandHandler[];
+    /**
+     * The commands to registered with the sso command bot. Each sso command should implement the interface {@link TeamsFxBotSsoCommandHandler} so that it can be correctly handled by this command bot.
+     */
+    ssoCommands?: TeamsFxBotSsoCommandHandler[];
 }
 
 /**
@@ -533,7 +725,7 @@ export declare class ConversationBot {
      * });
      * ```
      */
-    requestHandler(req: WebRequest, res: WebResponse, logic?: (context: TurnContext_2) => Promise<any>): Promise<void>;
+    requestHandler(req: WebRequest, res: WebResponse, logic?: (context: TurnContext) => Promise<any>): Promise<void>;
 }
 
 /**
@@ -558,6 +750,10 @@ export declare interface ConversationOptions {
     adapterConfig?: {
         [key: string]: unknown;
     };
+    /**
+     * Configurations for sso command bot
+     */
+    ssoConfig?: BotSsoConfig;
     /**
      * The command part.
      */
@@ -684,6 +880,59 @@ export declare function createPfxCertOption(pfx: string | Buffer, options?: {
     passphrase?: string;
 }): SecureContextOptions;
 
+/**
+ * Default SSO execution activity handler
+ */
+export declare class DefaultBotSsoExecutionActivityHandler extends TeamsActivityHandler implements BotSsoExecutionActivityHandler {
+    private ssoExecutionDialog;
+    private userState;
+    private conversationState;
+    private dialogState;
+    /**
+     * Creates a new instance of the DefaultBotSsoExecutionActivityHandler.
+     * @param ssoConfig configuration for SSO command bot
+     *
+     * @remarks
+     * In the constructor, it uses BotSsoConfig parameter which from {@link ConversationBot} options to initialize {@link BotSsoExecutionDialog}.
+     * It also need to register an event handler for the message event which trigger {@link BotSsoExecutionDialog} instance.
+     */
+    constructor(ssoConfig: BotSsoConfig);
+    /**
+     * Add TeamsFxBotSsoCommandHandler instance to SSO execution dialog
+     * @param handler {@link BotSsoExecutionDialogHandler} callback function
+     * @param triggerPatterns The trigger pattern
+     *
+     * @remarks
+     * This function is used to add SSO command to {@link BotSsoExecutionDialog} instance.
+     */
+    addCommand(handler: BotSsoExecutionDialogHandler, triggerPatterns: TriggerPatterns): void;
+    /**
+     * Called to initiate the event emission process.
+     * @param context The context object for the current turn.
+     */
+    run(context: TurnContext): Promise<void>;
+    /**
+     * Receives invoke activities with Activity name of 'signin/verifyState'.
+     * @param context A context object for this turn.
+     * @param query Signin state (part of signin action auth flow) verification invoke query.
+     * @returns A promise that represents the work queued.
+     *
+     * @remarks
+     * It should trigger {@link BotSsoExecutionDialog} instance to handle signin process
+     */
+    handleTeamsSigninVerifyState(context: TurnContext, query: SigninStateVerificationQuery): Promise<void>;
+    /**
+     * Receives invoke activities with Activity name of 'signin/tokenExchange'
+     * @param context A context object for this turn.
+     * @param query Signin state (part of signin action auth flow) verification invoke query
+     * @returns A promise that represents the work queued.
+     *
+     * @remark
+     * It should trigger {@link BotSsoExecutionDialog} instance to handle signin process
+     */
+    handleTeamsSigninTokenExchange(context: TurnContext, query: SigninStateVerificationQuery): Promise<void>;
+}
+
 /**
  * Error code to trace the error types.
  */
@@ -708,6 +957,30 @@ export declare enum ErrorCode {
      * Channel is not supported error.
      */
     ChannelNotSupported = "ChannelNotSupported",
+    /**
+     * Failed to retrieve sso token
+     */
+    FailedToRetrieveSsoToken = "FailedToRetrieveSsoToken",
+    /**
+     * Failed to process sso handler
+     */
+    FailedToProcessSsoHandler = "FailedToProcessSsoHandler",
+    /**
+     * Cannot find command
+     */
+    CannotFindCommand = "CannotFindCommand",
+    /**
+     * Failed to run sso step
+     */
+    FailedToRunSsoStep = "FailedToRunSsoStep",
+    /**
+     * Failed to run dedup step
+     */
+    FailedToRunDedupStep = "FailedToRunDedupStep",
+    /**
+     * Sso activity handler is undefined
+     */
+    SsoActivityHandlerIsUndefined = "SsoActivityHandlerIsUndefined",
     /**
      * Runtime is not supported error.
      */
@@ -857,7 +1130,7 @@ export declare class InvokeResponseFactory {
      *
      * @returns {InvokeResponse} An InvokeResponse object.
      */
-    static textMessage(message: string): InvokeResponse_2;
+    static textMessage(message: string): InvokeResponse;
     /**
      * Create an invoke response from an adaptive card.
      *
@@ -869,7 +1142,7 @@ export declare class InvokeResponseFactory {
      *
      * @returns {InvokeResponse} An InvokeResponse object.
      */
-    static adaptiveCard(card: IAdaptiveCard): InvokeResponse_2;
+    static adaptiveCard(card: IAdaptiveCard): InvokeResponse;
     /**
      * Create an invoke response with error code and message.
      *
@@ -883,7 +1156,7 @@ export declare class InvokeResponseFactory {
      *
      * @returns {InvokeResponse} An InvokeResponse object.
      */
-    static errorResponse(errorCode: InvokeResponseErrorCode, errorMessage: string): InvokeResponse_2;
+    static errorResponse(errorCode: InvokeResponseErrorCode, errorMessage: string): InvokeResponse;
     /**
      * Create an invoke response with status code and response value.
      * @param statusCode The status code.
@@ -891,7 +1164,7 @@ export declare class InvokeResponseFactory {
      *
      * @returns {InvokeResponse} An InvokeResponse object.
      */
-    static createInvokeResponse(statusCode: StatusCodes, body?: unknown): InvokeResponse_2;
+    static createInvokeResponse(statusCode: StatusCodes, body?: unknown): InvokeResponse;
 }
 
 /**
@@ -1032,14 +1305,14 @@ export declare class MessageBuilder {
      * });
      * ```
      */
-    static attachAdaptiveCard<TData extends object>(cardTemplate: unknown, data: TData): Partial<Activity_2>;
+    static attachAdaptiveCard<TData extends object>(cardTemplate: unknown, data: TData): Partial<Activity>;
     /**
      * Build a bot message activity attached with an adaptive card.
      *
      * @param card The adaptive card content.
      * @returns A bot message activity attached with an adaptive card.
      */
-    static attachAdaptiveCardWithoutData(card: unknown): Partial<Activity_2>;
+    static attachAdaptiveCardWithoutData(card: unknown): Partial<Activity>;
     /**
      * Build a bot message activity attached with an hero card.
      *
@@ -1060,7 +1333,7 @@ export declare class MessageBuilder {
      * );
      * ```
      */
-    static attachHeroCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<HeroCard>): Partial<Activity_2>;
+    static attachHeroCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<HeroCard>): Partial<Activity>;
     /**
      * Returns an attachment for a sign-in card.
      *
@@ -1073,20 +1346,20 @@ export declare class MessageBuilder {
      * @remarks
      * For channels that don't natively support sign-in cards, an alternative message is rendered.
      */
-    static attachSigninCard(title: string, url: string, text?: string): Partial<Activity_2>;
+    static attachSigninCard(title: string, url: string, text?: string): Partial<Activity>;
     /**
      * Build a bot message activity attached with an Office 365 connector card.
      *
      * @param card A description of the Office 365 connector card.
      * @returns A bot message activity attached with an Office 365 connector card.
      */
-    static attachO365ConnectorCard(card: O365ConnectorCard): Partial<Activity_2>;
+    static attachO365ConnectorCard(card: O365ConnectorCard): Partial<Activity>;
     /**
      * Build a message activity attached with a receipt card.
      * @param card A description of the receipt card.
      * @returns A message activity attached with a receipt card.
      */
-    static AttachReceiptCard(card: ReceiptCard): Partial<Activity_2>;
+    static AttachReceiptCard(card: ReceiptCard): Partial<Activity>;
     /**
      *
      * @param title The card title.
@@ -1096,13 +1369,13 @@ export declare class MessageBuilder {
      * @param other Optional. Any additional properties to include on the card.
      * @returns A message activity attached with a thumbnail card
      */
-    static attachThumbnailCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<ThumbnailCard>): Partial<Activity_2>;
+    static attachThumbnailCard(title: string, images?: (CardImage | string)[], buttons?: (CardAction | string)[], other?: Partial<ThumbnailCard>): Partial<Activity>;
     /**
      * Add an attachement to a bot activity.
      * @param attachement The attachment object to attach.
      * @returns A message activity with an attachment.
      */
-    static attachContent(attachement: Attachment): Partial<Activity_2>;
+    static attachContent(attachement: Attachment): Partial<Activity>;
 }
 
 /**
@@ -1809,6 +2082,26 @@ export declare interface TeamsFxBotCommandHandler {
     handleCommandReceived(context: TurnContext, message: CommandMessage): Promise<string | Partial<Activity> | void>;
 }
 
+/**
+ * Interface for a command handler that can process sso command to a TeamsFx bot and return a response.
+ */
+export declare interface TeamsFxBotSsoCommandHandler {
+    /**
+     * The string or regular expression patterns that can trigger this handler.
+     */
+    triggerPatterns: TriggerPatterns;
+    /**
+     * Handles a bot command received activity.
+     *
+     * @param context The bot context.
+     * @param message The command message the user types from Teams.
+     * @param ssoToken The sso token which can be used to exchange access token for the bot.
+     * @returns A `Promise` representing an activity or text to send as the command response.
+     * Or no return value if developers want to send the response activity by themselves in this method.
+     */
+    handleCommandReceived(context: TurnContext, message: CommandMessage, ssoToken: TeamsBotSsoPromptTokenResponse): Promise<string | Partial<Activity> | void>;
+}
+
 /**
  * TeamsFx interface that provides credential and configuration.
  */