@microsoft/agents-hosting 0.5.12-g2d752e9b13 → 0.5.16-g6bdf69cc43

package/dist/src/app/authorization.d.ts

@@ -0,0 +1,293 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { TurnContext } from '../turnContext';
+import { TurnState } from './turnState';
+import { Storage } from '../storage';
+import { OAuthFlow, TokenResponse } from '../oauth';
+import { Activity } from '@microsoft/agents-activity';
+/**
+ * Interface representing the state of a sign-in process.
+ * @interface SignInState
+ */
+export interface SignInState {
+    /** Optional activity to continue with after sign-in completion. */
+    continuationActivity?: Activity;
+    /** Identifier of the auth handler being used. */
+    handlerId?: string;
+    /** Whether the sign-in process has been completed. */
+    completed?: boolean;
+}
+/**
+ * Interface defining an authorization handler for OAuth flows.
+ * @interface AuthHandler
+ */
+export interface AuthHandler {
+    /** Connection name for the auth provider. */
+    name?: string;
+    /** The OAuth flow implementation. */
+    flow?: OAuthFlow;
+    /** Title to display on auth cards/UI. */
+    title?: string;
+    /** Text to display on auth cards/UI. */
+    text?: string;
+}
+/**
+ * Options for configuring user authorization.
+ * Contains settings to configure OAuth connections.
+ * @interface AuthorizationHandlers
+ */
+export interface AuthorizationHandlers extends Record<string, AuthHandler> {
+}
+/**
+ * Class responsible for managing authorization and OAuth flows.
+ * Handles multiple OAuth providers and manages the complete authentication lifecycle.
+ *
+ * @remarks
+ * The Authorization class provides a centralized way to handle OAuth authentication
+ * flows within the agent application. It supports multiple authentication handlers,
+ * token exchange, on-behalf-of flows, and provides event handlers for success/failure scenarios.
+ *
+ * Key features:
+ * - Multiple OAuth provider support
+ * - Token caching and exchange
+ * - On-behalf-of (OBO) token flows
+ * - Sign-in success/failure event handling
+ * - Automatic configuration from environment variables
+ *
+ * Example usage:
+ * ```typescript
+ * const auth = new Authorization(storage, {
+ *   'microsoft': {
+ *     name: 'Microsoft',
+ *     title: 'Sign in with Microsoft',
+ *     text: 'Please sign in'
+ *   }
+ * });
+ *
+ * auth.onSignInSuccess(async (context, state) => {
+ *   await context.sendActivity('Welcome! You are now signed in.');
+ * });
+ * ```
+ */
+export declare class Authorization {
+    private storage;
+    /**
+     * Dictionary of configured authentication handlers.
+     * @public
+     */
+    authHandlers: AuthorizationHandlers;
+    /**
+     * Creates a new instance of Authorization.
+     *
+     * @param storage - The storage system to use for state management.
+     * @param authHandlers - Configuration for OAuth providers.
+     * @throws {Error} If storage is null/undefined or no auth handlers are provided.
+     *
+     * @remarks
+     * The constructor initializes all configured auth handlers and sets up OAuth flows.
+     * It automatically configures handler properties from environment variables if not provided:
+     * - Connection name: {handlerId}_connectionName
+     * - Connection title: {handlerId}_connectionTitle
+     * - Connection text: {handlerId}_connectionText
+     *
+     * Example usage:
+     * ```typescript
+     * const auth = new Authorization(storage, {
+     *   'microsoft': {
+     *     name: 'Microsoft',
+     *     title: 'Sign in with Microsoft'
+     *   },
+     *   'google': {
+     *     // Will use GOOGLE_connectionName from env vars
+     *   }
+     * });
+     * ```
+     */
+    constructor(storage: Storage, authHandlers: AuthorizationHandlers);
+    /**
+     * Gets the token for a specific auth handler.
+     *
+     * @param context - The context object for the current turn.
+     * @param authHandlerId - ID of the auth handler to use.
+     * @returns A promise that resolves to the token response from the OAuth provider.
+     * @throws {Error} If the auth handler is not configured.
+     * @public
+     *
+     * @remarks
+     * This method retrieves an existing token for the specified auth handler.
+     * The token may be cached and will be retrieved from the OAuth provider if needed.
+     *
+     * Example usage:
+     * ```typescript
+     * const tokenResponse = await auth.getToken(context, 'microsoft');
+     * if (tokenResponse.token) {
+     *   console.log('User is authenticated');
+     * }
+     * ```
+     */
+    getToken(context: TurnContext, authHandlerId: string): Promise<TokenResponse>;
+    /**
+     * Gets the auth handler by ID or throws an error if not found.
+     *
+     * @param authHandlerId - ID of the auth handler to retrieve.
+     * @returns The auth handler instance.
+     * @throws {Error} If the auth handler with the specified ID is not configured.
+     * @private
+     */
+    private getAuthHandlerOrThrow;
+    /**
+     * Exchanges a token for a new token with different scopes.
+     *
+     * @param context - The context object for the current turn.
+     * @param scopes - Array of scopes to request for the new token.
+     * @param authHandlerId - ID of the auth handler to use.
+     * @returns A promise that resolves to the exchanged token response.
+     * @throws {Error} If the auth handler is not configured.
+     * @public
+     *
+     * @remarks
+     * This method handles token exchange scenarios, particularly for on-behalf-of (OBO) flows.
+     * It checks if the current token is exchangeable (e.g., has audience starting with 'api://')
+     * and performs the appropriate token exchange using MSAL.
+     *
+     * Example usage:
+     * ```typescript
+     * const exchangedToken = await auth.exchangeToken(
+     *   context,
+     *   ['https://graph.microsoft.com/.default'],
+     *   'microsoft'
+     * );
+     * ```
+     */
+    exchangeToken(context: TurnContext, scopes: string[], authHandlerId: string): Promise<TokenResponse>;
+    /**
+     * Checks if a token is exchangeable for an on-behalf-of flow.
+     *
+     * @param token - The token to check.
+     * @returns True if the token is exchangeable, false otherwise.
+     * @private
+     */
+    private isExchangeable;
+    /**
+     * Handles on-behalf-of token exchange using MSAL.
+     *
+     * @param context - The context object for the current turn.
+     * @param token - The token to exchange.
+     * @param scopes - Array of scopes to request for the new token.
+     * @returns A promise that resolves to the exchanged token response.
+     * @private
+     */
+    private handleObo;
+    /**
+     * Begins or continues an OAuth flow.
+     *
+     * @param context - The context object for the current turn.
+     * @param state - The state object for the current turn.
+     * @param authHandlerId - ID of the auth handler to use.
+     * @returns A promise that resolves to the token response from the OAuth provider.
+     * @throws {Error} If the auth handler is not configured.
+     * @public
+     *
+     * @remarks
+     * This method manages the complete OAuth authentication flow:
+     * - If no flow is active, it begins a new OAuth flow and shows the sign-in card
+     * - If a flow is active, it continues the flow and processes the authentication response
+     * - Handles success/failure callbacks and updates the sign-in state accordingly
+     *
+     * The method automatically manages the sign-in state and continuation activities,
+     * allowing the conversation to resume after successful authentication.
+     *
+     * Example usage:
+     * ```typescript
+     * const tokenResponse = await auth.beginOrContinueFlow(context, state, 'microsoft');
+     * if (tokenResponse && tokenResponse.token) {
+     *   // User is now authenticated
+     *   await context.sendActivity('Authentication successful!');
+     * }
+     * ```
+     */
+    beginOrContinueFlow(context: TurnContext, state: TurnState, authHandlerId: string, secRoute?: boolean): Promise<TokenResponse>;
+    /**
+     * Signs out the current user.
+     *
+     * @param context - The context object for the current turn.
+     * @param state - The state object for the current turn.
+     * @param authHandlerId - Optional ID of the auth handler to use for sign out. If not provided, signs out from all handlers.
+     * @returns A promise that resolves when sign out is complete.
+     * @throws {Error} If the specified auth handler is not configured.
+     * @public
+     *
+     * @remarks
+     * This method clears the user's token and resets the authentication state.
+     * If no specific authHandlerId is provided, it signs out from all configured handlers.
+     * This ensures complete cleanup of authentication state across all providers.
+     *
+     * Example usage:
+     * ```typescript
+     * // Sign out from specific handler
+     * await auth.signOut(context, state, 'microsoft');
+     *
+     * // Sign out from all handlers
+     * await auth.signOut(context, state);
+     * ```
+     */
+    signOut(context: TurnContext, state: TurnState, authHandlerId?: string): Promise<void>;
+    /**
+     * Private handler for successful sign-in events.
+     * @private
+     */
+    _signInSuccessHandler: ((context: TurnContext, state: TurnState, authHandlerId?: string) => Promise<void>) | null;
+    /**
+     * Sets a handler to be called when sign-in is successfully completed.
+     *
+     * @param handler - The handler function to call on successful sign-in.
+     * @public
+     *
+     * @remarks
+     * This method allows you to register a callback that will be invoked whenever
+     * a user successfully completes the authentication process. The handler receives
+     * the turn context, state, and the ID of the auth handler that was used.
+     *
+     * Example usage:
+     * ```typescript
+     * auth.onSignInSuccess(async (context, state, authHandlerId) => {
+     *   await context.sendActivity(`Welcome! You signed in using ${authHandlerId}.`);
+     *   // Perform any post-authentication setup
+     * });
+     * ```
+     */
+    onSignInSuccess(handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => Promise<void>): void;
+    /**
+     * Private handler for failed sign-in events.
+     * @private
+     */
+    _signInFailureHandler: ((context: TurnContext, state: TurnState, authHandlerId?: string, errorMessage?: string) => Promise<void>) | null;
+    /**
+     * Sets a handler to be called when sign-in fails.
+     *
+     * @param handler - The handler function to call on sign-in failure.
+     * @public
+     *
+     * @remarks
+     * This method allows you to register a callback that will be invoked whenever
+     * a user's authentication attempt fails. The handler receives the turn context,
+     * state, auth handler ID, and an optional error message describing the failure.
+     *
+     * Common failure scenarios include:
+     * - User cancels the authentication process
+     * - Invalid credentials or expired tokens
+     * - Network connectivity issues
+     * - OAuth provider errors
+     *
+     * Example usage:
+     * ```typescript
+     * auth.onSignInFailure(async (context, state, authHandlerId, errorMessage) => {
+     *   await context.sendActivity(`Sign-in failed: ${errorMessage || 'Unknown error'}`);
+     *   await context.sendActivity('Please try signing in again.');
+     * });
+     * ```
+     */
+    onSignInFailure(handler: (context: TurnContext, state: TurnState, authHandlerId?: string, errorMessage?: string) => Promise<void>): void;
+}

package/dist/src/app/authorization.js

@@ -0,0 +1,375 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Authorization = void 0;
+const logger_1 = require("../logger");
+const oauth_1 = require("../oauth");
+const auth_1 = require("../auth");
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const logger = (0, logger_1.debug)('agents:authorization');
+/**
+ * Class responsible for managing authorization and OAuth flows.
+ * Handles multiple OAuth providers and manages the complete authentication lifecycle.
+ *
+ * @remarks
+ * The Authorization class provides a centralized way to handle OAuth authentication
+ * flows within the agent application. It supports multiple authentication handlers,
+ * token exchange, on-behalf-of flows, and provides event handlers for success/failure scenarios.
+ *
+ * Key features:
+ * - Multiple OAuth provider support
+ * - Token caching and exchange
+ * - On-behalf-of (OBO) token flows
+ * - Sign-in success/failure event handling
+ * - Automatic configuration from environment variables
+ *
+ * Example usage:
+ * ```typescript
+ * const auth = new Authorization(storage, {
+ *   'microsoft': {
+ *     name: 'Microsoft',
+ *     title: 'Sign in with Microsoft',
+ *     text: 'Please sign in'
+ *   }
+ * });
+ *
+ * auth.onSignInSuccess(async (context, state) => {
+ *   await context.sendActivity('Welcome! You are now signed in.');
+ * });
+ * ```
+ */
+class Authorization {
+    /**
+     * Creates a new instance of Authorization.
+     *
+     * @param storage - The storage system to use for state management.
+     * @param authHandlers - Configuration for OAuth providers.
+     * @throws {Error} If storage is null/undefined or no auth handlers are provided.
+     *
+     * @remarks
+     * The constructor initializes all configured auth handlers and sets up OAuth flows.
+     * It automatically configures handler properties from environment variables if not provided:
+     * - Connection name: {handlerId}_connectionName
+     * - Connection title: {handlerId}_connectionTitle
+     * - Connection text: {handlerId}_connectionText
+     *
+     * Example usage:
+     * ```typescript
+     * const auth = new Authorization(storage, {
+     *   'microsoft': {
+     *     name: 'Microsoft',
+     *     title: 'Sign in with Microsoft'
+     *   },
+     *   'google': {
+     *     // Will use GOOGLE_connectionName from env vars
+     *   }
+     * });
+     * ```
+     */
+    constructor(storage, authHandlers) {
+        var _a, _b, _c;
+        this.storage = storage;
+        /**
+         * Private handler for successful sign-in events.
+         * @private
+         */
+        this._signInSuccessHandler = null;
+        /**
+         * Private handler for failed sign-in events.
+         * @private
+         */
+        this._signInFailureHandler = null;
+        if (storage === undefined || storage === null) {
+            throw new Error('Storage is required for UserAuthorization');
+        }
+        if (authHandlers === undefined || Object.keys(authHandlers).length === 0) {
+            throw new Error('The authorization does not have any auth handlers');
+        }
+        this.authHandlers = authHandlers;
+        for (const ah in this.authHandlers) {
+            if (this.authHandlers[ah].name === undefined && process.env[ah + '_connectionName'] === undefined) {
+                throw new Error(`AuthHandler name ${ah}_connectionName not set in autorization and not found in env vars.`);
+            }
+            const currentAuthHandler = this.authHandlers[ah];
+            currentAuthHandler.name = (_a = currentAuthHandler.name) !== null && _a !== void 0 ? _a : process.env[ah + '_connectionName'];
+            currentAuthHandler.title = (_b = currentAuthHandler.title) !== null && _b !== void 0 ? _b : process.env[ah + '_connectionTitle'];
+            currentAuthHandler.text = (_c = currentAuthHandler.text) !== null && _c !== void 0 ? _c : process.env[ah + '_connectionText'];
+            currentAuthHandler.flow = new oauth_1.OAuthFlow(this.storage, currentAuthHandler.name, null, currentAuthHandler.title, currentAuthHandler.text);
+        }
+        logger.info('Authorization handlers configured with', Object.keys(this.authHandlers).length, 'handlers');
+    }
+    /**
+     * Gets the token for a specific auth handler.
+     *
+     * @param context - The context object for the current turn.
+     * @param authHandlerId - ID of the auth handler to use.
+     * @returns A promise that resolves to the token response from the OAuth provider.
+     * @throws {Error} If the auth handler is not configured.
+     * @public
+     *
+     * @remarks
+     * This method retrieves an existing token for the specified auth handler.
+     * The token may be cached and will be retrieved from the OAuth provider if needed.
+     *
+     * Example usage:
+     * ```typescript
+     * const tokenResponse = await auth.getToken(context, 'microsoft');
+     * if (tokenResponse.token) {
+     *   console.log('User is authenticated');
+     * }
+     * ```
+     */
+    async getToken(context, authHandlerId) {
+        var _a;
+        logger.info('getToken from user token service for authHandlerId:', authHandlerId);
+        const authHandler = this.getAuthHandlerOrThrow(authHandlerId);
+        return await ((_a = authHandler.flow) === null || _a === void 0 ? void 0 : _a.getUserToken(context));
+    }
+    /**
+     * Gets the auth handler by ID or throws an error if not found.
+     *
+     * @param authHandlerId - ID of the auth handler to retrieve.
+     * @returns The auth handler instance.
+     * @throws {Error} If the auth handler with the specified ID is not configured.
+     * @private
+     */
+    getAuthHandlerOrThrow(authHandlerId) {
+        if (!Object.prototype.hasOwnProperty.call(this.authHandlers, authHandlerId)) {
+            throw new Error(`AuthHandler with ID ${authHandlerId} not configured`);
+        }
+        return this.authHandlers[authHandlerId];
+    }
+    /**
+     * Exchanges a token for a new token with different scopes.
+     *
+     * @param context - The context object for the current turn.
+     * @param scopes - Array of scopes to request for the new token.
+     * @param authHandlerId - ID of the auth handler to use.
+     * @returns A promise that resolves to the exchanged token response.
+     * @throws {Error} If the auth handler is not configured.
+     * @public
+     *
+     * @remarks
+     * This method handles token exchange scenarios, particularly for on-behalf-of (OBO) flows.
+     * It checks if the current token is exchangeable (e.g., has audience starting with 'api://')
+     * and performs the appropriate token exchange using MSAL.
+     *
+     * Example usage:
+     * ```typescript
+     * const exchangedToken = await auth.exchangeToken(
+     *   context,
+     *   ['https://graph.microsoft.com/.default'],
+     *   'microsoft'
+     * );
+     * ```
+     */
+    async exchangeToken(context, scopes, authHandlerId) {
+        var _a;
+        logger.info('getToken from user token service for authHandlerId:', authHandlerId);
+        const authHandler = this.getAuthHandlerOrThrow(authHandlerId);
+        const tokenResponse = await ((_a = authHandler.flow) === null || _a === void 0 ? void 0 : _a.getUserToken(context));
+        if (this.isExchangeable(tokenResponse.token)) {
+            return await this.handleObo(context, tokenResponse.token, scopes);
+        }
+        return tokenResponse;
+    }
+    /**
+     * Checks if a token is exchangeable for an on-behalf-of flow.
+     *
+     * @param token - The token to check.
+     * @returns True if the token is exchangeable, false otherwise.
+     * @private
+     */
+    isExchangeable(token) {
+        var _a;
+        if (!token || typeof token !== 'string') {
+            return false;
+        }
+        const payload = jsonwebtoken_1.default.decode(token);
+        return ((_a = payload === null || payload === void 0 ? void 0 : payload.aud) === null || _a === void 0 ? void 0 : _a.indexOf('api://')) === 0;
+    }
+    /**
+     * Handles on-behalf-of token exchange using MSAL.
+     *
+     * @param context - The context object for the current turn.
+     * @param token - The token to exchange.
+     * @param scopes - Array of scopes to request for the new token.
+     * @returns A promise that resolves to the exchanged token response.
+     * @private
+     */
+    async handleObo(context, token, scopes) {
+        const msalTokenProvider = new auth_1.MsalTokenProvider();
+        const authConfig = context.adapter.authConfig;
+        const newToken = await msalTokenProvider.acquireTokenOnBehalfOf(authConfig, scopes, token);
+        return { token: newToken };
+    }
+    /**
+     * Begins or continues an OAuth flow.
+     *
+     * @param context - The context object for the current turn.
+     * @param state - The state object for the current turn.
+     * @param authHandlerId - ID of the auth handler to use.
+     * @returns A promise that resolves to the token response from the OAuth provider.
+     * @throws {Error} If the auth handler is not configured.
+     * @public
+     *
+     * @remarks
+     * This method manages the complete OAuth authentication flow:
+     * - If no flow is active, it begins a new OAuth flow and shows the sign-in card
+     * - If a flow is active, it continues the flow and processes the authentication response
+     * - Handles success/failure callbacks and updates the sign-in state accordingly
+     *
+     * The method automatically manages the sign-in state and continuation activities,
+     * allowing the conversation to resume after successful authentication.
+     *
+     * Example usage:
+     * ```typescript
+     * const tokenResponse = await auth.beginOrContinueFlow(context, state, 'microsoft');
+     * if (tokenResponse && tokenResponse.token) {
+     *   // User is now authenticated
+     *   await context.sendActivity('Authentication successful!');
+     * }
+     * ```
+     */
+    async beginOrContinueFlow(context, state, authHandlerId, secRoute = true) {
+        var _a, _b, _c, _d, _e;
+        const authHandler = this.getAuthHandlerOrThrow(authHandlerId);
+        logger.info('beginOrContinueFlow for authHandlerId:', authHandlerId);
+        const signInState = state.getValue('user.__SIGNIN_STATE_') || { continuationActivity: undefined, handlerId: undefined, completed: false };
+        const flow = authHandler.flow;
+        let tokenResponse;
+        tokenResponse = await ((_a = authHandler.flow) === null || _a === void 0 ? void 0 : _a.getUserToken(context));
+        if ((tokenResponse === null || tokenResponse === void 0 ? void 0 : tokenResponse.token) && tokenResponse.token.length > 0) {
+            (_b = authHandler.flow) === null || _b === void 0 ? true : delete _b.state.eTag;
+            authHandler.flow.state.flowStarted = false;
+            await ((_c = authHandler.flow) === null || _c === void 0 ? void 0 : _c.setFlowState(context, authHandler.flow.state));
+            if (secRoute) {
+                return tokenResponse;
+            }
+        }
+        if (flow.state === null || ((_d = flow.state) === null || _d === void 0 ? void 0 : _d.flowStarted) === false || ((_e = flow.state) === null || _e === void 0 ? void 0 : _e.flowStarted) === undefined) {
+            tokenResponse = await flow.beginFlow(context);
+            if (secRoute && (tokenResponse === null || tokenResponse === void 0 ? void 0 : tokenResponse.token) === undefined) {
+                signInState.continuationActivity = context.activity;
+                signInState.handlerId = authHandlerId;
+                state.setValue('user.__SIGNIN_STATE_', signInState);
+            }
+        }
+        else {
+            tokenResponse = await flow.continueFlow(context);
+            if (tokenResponse && tokenResponse.token) {
+                if (this._signInSuccessHandler) {
+                    await this._signInSuccessHandler(context, state, authHandlerId);
+                }
+                if (secRoute) {
+                    state.deleteValue('user.__SIGNIN_STATE_');
+                }
+            }
+            else {
+                logger.warn('Failed to complete OAuth flow, no token received');
+                if (this._signInFailureHandler) {
+                    await this._signInFailureHandler(context, state, authHandlerId, 'Failed to complete the OAuth flow');
+                }
+                // signInState!.completed = false
+                // state.setValue('user.__SIGNIN_STATE_', signInState)
+            }
+        }
+        return tokenResponse;
+    }
+    /**
+     * Signs out the current user.
+     *
+     * @param context - The context object for the current turn.
+     * @param state - The state object for the current turn.
+     * @param authHandlerId - Optional ID of the auth handler to use for sign out. If not provided, signs out from all handlers.
+     * @returns A promise that resolves when sign out is complete.
+     * @throws {Error} If the specified auth handler is not configured.
+     * @public
+     *
+     * @remarks
+     * This method clears the user's token and resets the authentication state.
+     * If no specific authHandlerId is provided, it signs out from all configured handlers.
+     * This ensures complete cleanup of authentication state across all providers.
+     *
+     * Example usage:
+     * ```typescript
+     * // Sign out from specific handler
+     * await auth.signOut(context, state, 'microsoft');
+     *
+     * // Sign out from all handlers
+     * await auth.signOut(context, state);
+     * ```
+     */
+    async signOut(context, state, authHandlerId) {
+        var _a;
+        logger.info('signOut for authHandlerId:', authHandlerId);
+        if (authHandlerId === undefined) { // aw
+            for (const ah in this.authHandlers) {
+                const flow = this.authHandlers[ah].flow;
+                await (flow === null || flow === void 0 ? void 0 : flow.signOut(context));
+            }
+        }
+        else {
+            const authHandler = this.getAuthHandlerOrThrow(authHandlerId);
+            await ((_a = authHandler.flow) === null || _a === void 0 ? void 0 : _a.signOut(context));
+        }
+    }
+    /**
+     * Sets a handler to be called when sign-in is successfully completed.
+     *
+     * @param handler - The handler function to call on successful sign-in.
+     * @public
+     *
+     * @remarks
+     * This method allows you to register a callback that will be invoked whenever
+     * a user successfully completes the authentication process. The handler receives
+     * the turn context, state, and the ID of the auth handler that was used.
+     *
+     * Example usage:
+     * ```typescript
+     * auth.onSignInSuccess(async (context, state, authHandlerId) => {
+     *   await context.sendActivity(`Welcome! You signed in using ${authHandlerId}.`);
+     *   // Perform any post-authentication setup
+     * });
+     * ```
+     */
+    onSignInSuccess(handler) {
+        this._signInSuccessHandler = handler;
+    }
+    /**
+     * Sets a handler to be called when sign-in fails.
+     *
+     * @param handler - The handler function to call on sign-in failure.
+     * @public
+     *
+     * @remarks
+     * This method allows you to register a callback that will be invoked whenever
+     * a user's authentication attempt fails. The handler receives the turn context,
+     * state, auth handler ID, and an optional error message describing the failure.
+     *
+     * Common failure scenarios include:
+     * - User cancels the authentication process
+     * - Invalid credentials or expired tokens
+     * - Network connectivity issues
+     * - OAuth provider errors
+     *
+     * Example usage:
+     * ```typescript
+     * auth.onSignInFailure(async (context, state, authHandlerId, errorMessage) => {
+     *   await context.sendActivity(`Sign-in failed: ${errorMessage || 'Unknown error'}`);
+     *   await context.sendActivity('Please try signing in again.');
+     * });
+     * ```
+     */
+    onSignInFailure(handler) {
+        this._signInFailureHandler = handler;
+    }
+}
+exports.Authorization = Authorization;
+//# sourceMappingURL=authorization.js.map

package/dist/src/app/authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../../../src/app/authorization.ts"],"names":[],"mappings":"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"}

package/dist/src/app/index.d.ts

@@ -3,7 +3,7 @@ export * from './agentApplicationBuilder';
 export * from './agentApplicationOptions';
 export * from './appRoute';
 export * from './attachmentDownloader';
-export * from './oauth/authorization';
+export * from './authorization';
 export * from './conversationUpdateEvents';
 export * from './routeHandler';
 export * from './routeSelector';