@microsoft/agents-hosting 0.1.49

package/src/invoke/tokenExchangeInvokeRequest.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents a token exchange invoke request.
+ */
+export interface TokenExchangeInvokeRequest {
+  /**
+   * The unique identifier for the request.
+   */
+  id: string
+  /**
+   * The name of the connection.
+   */
+  connectionName: string
+  /**
+   * The token to be exchanged.
+   */
+  token: string
+}

package/src/logger.ts

@@ -0,0 +1,43 @@
+import createDebug, { Debugger } from 'debug'
+
+class Logger {
+  private loggers: { [level: string]: Debugger } = {}
+  private readonly levelColors: { [level: string]: string } = {
+    info: '2', // Green
+    warn: '3', // Yellow
+    error: '1', // Red
+    debug: '4' // Blue
+  }
+
+  constructor (namespace: string = '') {
+    this.initializeLoggers(namespace)
+  }
+
+  private initializeLoggers (namespace: string) {
+    for (const level of Object.keys(this.levelColors)) {
+      const logger = createDebug(`${namespace}:${level}`)
+      logger.color = this.levelColors[level]
+      this.loggers[level] = logger
+    }
+  }
+
+  info (message: string, ...args: any[]) {
+    this.loggers.info(message, ...args)
+  }
+
+  warn (message: string, ...args: any[]) {
+    this.loggers.warn(message, ...args)
+  }
+
+  error (message: string, ...args: any[]) {
+    this.loggers.error(message, ...args)
+  }
+
+  debug (message: string, ...args: any[]) {
+    this.loggers.debug(message, ...args)
+  }
+}
+
+export function debug (namespace: string): Logger {
+  return new Logger(namespace)
+}

package/src/messageFactory.ts

@@ -0,0 +1,177 @@
+/** * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */
+import { ActionTypes, Activity, ActivityTypes, Attachment, AttachmentLayoutTypes, CardAction, InputHints, SuggestedActions } from '@microsoft/agents-activity'
+
+/**
+ * A factory class for creating various types of message activities.
+ */
+export class MessageFactory {
+  /**
+   * Creates a text message activity.
+   * @param text The text of the message.
+   * @param speak (Optional) The text to be spoken by the agent.
+   * @param inputHint (Optional) The input hint for the message.
+   * @returns The created text message activity.
+   */
+  static text (text: string, speak?: string, inputHint?: InputHints | string): Activity {
+    let msgObj = {}
+    msgObj = {
+      type: ActivityTypes.Message,
+      text,
+      inputHint: inputHint || InputHints.AcceptingInput
+    }
+    if (speak) {
+      msgObj = { ...msgObj, speak }
+    }
+    const msg = Activity.fromObject(msgObj)
+    return msg
+  }
+
+  /**
+   * Creates a message activity with suggested actions.
+   * @param actions The suggested actions.
+   * @param text (Optional) The text of the message.
+   * @param speak (Optional) The text to be spoken by the agent.
+   * @param inputHint (Optional) The input hint for the message.
+   * @returns The created message activity with suggested actions.
+   */
+  static suggestedActions (
+    actions: Array<CardAction | string>,
+    text?: string,
+    speak?: string,
+    inputHint?: InputHints | string
+  ): Activity {
+    const formattedActions: CardAction[] = (actions || []).map((action) => {
+      if (typeof action === 'object') {
+        return action
+      } else {
+        return {
+          type: ActionTypes.ImBack,
+          value: { text: action.toString() },
+          title: action.toString(),
+          channelData: undefined
+        }
+      }
+    })
+    const msgObj = {
+      type: ActivityTypes.Message,
+      inputHint: inputHint || InputHints.AcceptingInput,
+      suggestedActions: { actions: formattedActions, to: [] } as SuggestedActions
+    }
+    const msg = Activity.fromObject(msgObj)
+    if (text) {
+      msg.text = text
+    }
+    if (speak) {
+      msg.speak = speak
+    }
+    return msg
+  }
+
+  /**
+   * Creates a message activity with a single attachment.
+   * @param attachment The attachment to include in the message.
+   * @param text (Optional) The text of the message.
+   * @param speak (Optional) The text to be spoken by the agent.
+   * @param inputHint (Optional) The input hint for the message.
+   * @returns The created message activity with an attachment.
+   */
+  static attachment (
+    attachment: Attachment,
+    text?: string,
+    speak?: string,
+    inputHint?: InputHints | string
+  ): Activity {
+    return attachmentActivity(AttachmentLayoutTypes.List, [attachment], text, speak, inputHint)
+  }
+
+  /**
+   * Creates a message activity with a list of attachments.
+   * @param attachments The list of attachments to include in the message.
+   * @param text (Optional) The text of the message.
+   * @param speak (Optional) The text to be spoken by the agent.
+   * @param inputHint (Optional) The input hint for the message.
+   * @returns The created message activity with a list of attachments.
+   */
+  static list (
+    attachments: Attachment[],
+    text?: string,
+    speak?: string,
+    inputHint?: InputHints | string
+  ): Activity {
+    return attachmentActivity(AttachmentLayoutTypes.List, attachments, text, speak, inputHint)
+  }
+
+  /**
+   * Creates a message activity with a carousel of attachments.
+   * @param attachments The list of attachments to include in the carousel.
+   * @param text (Optional) The text of the message.
+   * @param speak (Optional) The text to be spoken by the agent.
+   * @param inputHint (Optional) The input hint for the message.
+   * @returns The created message activity with a carousel of attachments.
+   */
+  static carousel (
+    attachments: Attachment[],
+    text?: string,
+    speak?: string,
+    inputHint?: InputHints | string
+  ): Activity {
+    return attachmentActivity(AttachmentLayoutTypes.Carousel, attachments, text, speak, inputHint)
+  }
+
+  /**
+   * Creates a message activity with content from a URL.
+   * @param url The URL of the content.
+   * @param contentType The content type of the attachment.
+   * @param name (Optional) The name of the attachment.
+   * @param text (Optional) The text of the message.
+   * @param speak (Optional) The text to be spoken by the agent.
+   * @param inputHint (Optional) The input hint for the message.
+   * @returns The created message activity with content from a URL.
+   */
+  static contentUrl (
+    url: string,
+    contentType: string,
+    name?: string,
+    text?: string,
+    speak?: string,
+    inputHint?: InputHints | string
+  ): Activity {
+    const a: Attachment = { contentType, contentUrl: url }
+    if (name) {
+      a.name = name
+    }
+    return attachmentActivity(AttachmentLayoutTypes.List, [a], text, speak, inputHint)
+  }
+}
+
+/**
+ * Creates a message activity with attachments.
+ * @param attachmentLayout The layout for the attachments.
+ * @param attachments The list of attachments to include in the message.
+ * @param text (Optional) The text of the message.
+ * @param speak (Optional) The text to be spoken by the agent.
+ * @param inputHint (Optional) The input hint for the message.
+ * @returns The created message activity with attachments.
+ */
+function attachmentActivity (
+  attachmentLayout: AttachmentLayoutTypes,
+  attachments: Attachment[],
+  text?: string,
+  speak?: string,
+  inputHint?: InputHints | string
+): Activity {
+  const msgObj = {
+    type: ActivityTypes.Message,
+    attachmentLayout,
+    attachments,
+    inputHint: inputHint || InputHints.AcceptingInput
+  }
+  const msg = Activity.fromObject(msgObj)
+  if (text) {
+    msg.text = text
+  }
+  if (speak) {
+    msg.speak = speak
+  }
+  return msg
+}

package/src/middlewareSet.ts

@@ -0,0 +1,76 @@
+/** * Copyright (c) Microsoft Corporation. All rights reserved. * Licensed under the MIT License. */
+import { TurnContext } from './turnContext'
+import { debug } from './logger'
+
+const logger = debug('agents:middleware')
+
+/**
+ * Interface for middleware.
+ */
+export interface Middleware {
+  onTurn: (context: TurnContext, next: () => Promise<void>) => Promise<void>
+}
+
+/**
+ * Type for middleware handler.
+ */
+export type MiddlewareHandler = (context: TurnContext, next: () => Promise<void>) => Promise<void>
+
+/**
+ * Represents a set of middleware.
+ */
+export class MiddlewareSet implements Middleware {
+  private readonly middleware: MiddlewareHandler[] = []
+
+  /**
+   * Initializes a new instance of the MiddlewareSet class.
+   * @param middlewares The middleware handlers or middleware objects to use.
+   */
+  constructor (...middlewares: Array<MiddlewareHandler | Middleware>) {
+    this.use(...middlewares)
+  }
+
+  /**
+   * Handles the turn of the middleware.
+   * @param context The turn context.
+   * @param next The next function to call.
+   * @returns A promise representing the asynchronous operation.
+   */
+  async onTurn (context: TurnContext, next: () => Promise<void>): Promise<void> {
+    return await this.run(context, next)
+  }
+
+  /**
+   * Adds middleware to the set.
+   * @param middlewares The middleware handlers or middleware objects to add.
+   * @returns The current MiddlewareSet instance.
+   */
+  use (...middlewares: Array<MiddlewareHandler | Middleware>): this {
+    middlewares.forEach((plugin) => {
+      if (typeof plugin === 'function' || (typeof plugin === 'object' && plugin.onTurn)) {
+        this.middleware.push(
+          typeof plugin === 'function' ? plugin : async (context, next) => await plugin.onTurn(context, next)
+        )
+      } else {
+        throw new Error('MiddlewareSet.use(): invalid plugin type being added.')
+      }
+    })
+    return this
+  }
+
+  /**
+   * Runs the middleware chain.
+   * @param context The turn context.
+   * @param next The next function to call.
+   * @returns A promise representing the asynchronous operation.
+   */
+  async run (context: TurnContext, next: () => Promise<void>): Promise<void> {
+    return await this.middleware.reduceRight<() => Promise<void>>(
+      (nextHandler, currentHandler) => async () => await currentHandler(context, nextHandler),
+    next
+    )().catch(err => {
+      logger.error('Error in middleware chain:', err)
+      throw err
+    })
+  }
+}

package/src/oauth/index.ts

@@ -0,0 +1,7 @@
+export * from './oauthCard'
+export * from './signingResource'
+export * from './tokenExchangeResource'
+export * from './tokenPostResource'
+export * from './userTokenClient'
+export * from './webChatOAuthFlow'
+export * from './tokenExchangeRequest'

package/src/oauth/oauthCard.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { CardAction } from '@microsoft/agents-activity'
+import { TokenExchangeResource } from './tokenExchangeResource'
+import { TokenPostResource } from './tokenPostResource'
+
+/**
+ * Represents an OAuth card.
+ */
+export interface OAuthCard {
+  /**
+   * The buttons associated with the OAuth card.
+   */
+  buttons: CardAction[]
+  /**
+   * The connection name for the OAuth card.
+   */
+  connectionName: string
+  /**
+   * The text content of the OAuth card.
+   */
+  text: string
+  /**
+   * The token exchange resource for the OAuth card.
+   */
+  tokenExchangeResource: TokenExchangeResource
+  /**
+   * The token post resource for the OAuth card.
+   */
+  tokenPostResource: TokenPostResource
+}

package/src/oauth/signingResource.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { TokenExchangeResource } from './tokenExchangeResource'
+import { TokenPostResource } from './tokenPostResource'
+
+/**
+ * Represents a resource for signing in.
+ */
+export interface SigningResource {
+  /**
+   * The link for signing in.
+   */
+  singingLink: string,
+  /**
+   * The resource for token exchange.
+   */
+  tokenExchangeResource: TokenExchangeResource,
+  /**
+   * The resource for token post.
+   */
+  tokenPostResource: TokenPostResource
+}

package/src/oauth/tokenExchangeRequest.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Represents a request for exchanging tokens.
+ */
+export interface TokenExchangeRequest {
+  /**
+   * The URI for the token exchange request.
+   */
+  uri?: string
+  /**
+   * The token to be exchanged.
+   */
+  token?: string
+  /**
+   * The ID associated with the token exchange request.
+   */
+  id?: string
+}

package/src/oauth/tokenExchangeResource.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Represents a resource for exchanging tokens.
+ */
+export interface TokenExchangeResource {
+  /**
+   * The ID of the token exchange resource.
+   */
+  id?: string
+  /**
+   * The URI of the token exchange resource.
+   */
+  uri?: string
+  /**
+   * The provider ID for the token exchange resource.
+   */
+  providerId?: string
+}

package/src/oauth/tokenPostResource.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * Represents a resource for posting tokens.
+ */
+export interface TokenPostResource {
+  /**
+   * The SAS URL for the token post resource.
+   */
+  sasUrl?: string
+}

package/src/oauth/userTokenClient.ts

@@ -0,0 +1,116 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import axios, { AxiosInstance } from 'axios'
+import { SigningResource } from './signingResource'
+import { Activity } from '@microsoft/agents-activity'
+import { debug } from '../logger'
+import { TokenExchangeRequest } from './tokenExchangeRequest'
+
+const logger = debug('agents:userTokenClient')
+
+/**
+ * Client for managing user tokens.
+ */
+export class UserTokenClient {
+  client: AxiosInstance
+
+  /**
+   * Creates a new instance of UserTokenClient.
+   * @param token The token to use for authentication.
+   */
+  constructor (token: string) {
+    const baseURL = 'https://api.botframework.com'
+    const axiosInstance = axios.create({
+      baseURL,
+      headers: {
+        Accept: 'application/json'
+      }
+    })
+    axiosInstance.defaults.headers.common.Authorization = `Bearer ${token}`
+    this.client = axiosInstance
+  }
+
+  /**
+   * Gets the user token.
+   * @param connectionName The connection name.
+   * @param channelId The channel ID.
+   * @param userId The user ID.
+   * @param code The optional code.
+   * @returns A promise that resolves to the user token.
+   */
+  async getUserToken (connectionName: string, channelId: string, userId: string, code?: string) {
+    try {
+      const params = { connectionName, channelId, userId, code }
+      const response = await this.client.get('/api/usertoken/GetToken', { params })
+      return response.data
+    } catch (error: any) {
+      if (error.response?.status !== 404) {
+        logger.error(error)
+      }
+      return null
+    }
+  }
+
+  /**
+   * Signs the user out.
+   * @param userId The user ID.
+   * @param connectionName The connection name.
+   * @param channelId The channel ID.
+   * @returns A promise that resolves when the sign-out operation is complete.
+   */
+  async signOut (userId: string, connectionName: string, channelId: string) {
+    try {
+      const params = { userId, connectionName, channelId }
+      const response = await this.client.delete('/api/usertoken/SignOut', { params })
+      return response.data
+    } catch (error: any) {
+      logger.error(error)
+      return null
+    }
+  }
+
+  /**
+   * Gets the sign-in resource.
+   * @param appId The application ID.
+   * @param cnxName The connection name.
+   * @param activity The activity.
+   * @returns A promise that resolves to the signing resource.
+   */
+  async getSignInResource (appId: string, cnxName: string, activity: Activity) : Promise<SigningResource> {
+    try {
+      const tokenExchangeState = {
+        ConnectionName: cnxName,
+        Conversation: activity.getConversationReference(),
+        RelatesTo: activity.RelatesTo,
+        MsAppId: appId
+      }
+      const state = Buffer.from(JSON.stringify(tokenExchangeState)).toString('base64')
+      const params = { state }
+      const response = await this.client.get('/api/botsignin/GetSignInResource', { params })
+      return response.data as SigningResource
+    } catch (error: any) {
+      logger.error(error)
+      throw error
+    }
+  }
+
+  /**
+   * Exchanges the token.
+   * @param userId The user ID.
+   * @param connectionName The connection name.
+   * @param channelId The channel ID.
+   * @param tokenExchangeRequest The token exchange request.
+   * @returns A promise that resolves to the exchanged token.
+   */
+  async exchangeTokenAsync (userId: string, connectionName: string, channelId: string, tokenExchangeRequest: TokenExchangeRequest) {
+    try {
+      const params = { userId, connectionName, channelId }
+      const response = await this.client.post('/api/usertoken/exchange', tokenExchangeRequest, { params })
+      return response.data
+    } catch (error: any) {
+      logger.error(error)
+      return null
+    }
+  }
+}

package/src/oauth/webChatOAuthFlow.ts

@@ -0,0 +1,123 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Attachment } from '@microsoft/agents-activity'
+import { UserTokenClient } from './userTokenClient'
+import { CloudAdapter } from '../cloudAdapter'
+import { CardFactory } from '../cards/cardFactory'
+import { AgentStatePropertyAccessor } from '../state/agentStatePropertyAccesor'
+import { UserState } from '../state/userState'
+import { TurnContext } from '../turnContext'
+import { MessageFactory } from '../messageFactory'
+import { debug } from '../logger'
+
+const logger = debug('agents:web-chat-oauth-flow')
+
+class FlowState {
+  public flowStarted: boolean = false
+  public userToken: string = ''
+  public flowExpires: number = 0
+}
+
+/**
+ * Manages the OAuth flow for Web Chat.
+ */
+export class WebChatOAuthFlow {
+  userTokenClient?: UserTokenClient
+  state: FlowState | null
+  flowStateAccessor: AgentStatePropertyAccessor<FlowState | null>
+
+  /**
+   * Creates a new instance of WebChatOAuthFlow.
+   * @param userState The user state.
+   */
+  constructor (userState: UserState) {
+    this.state = null
+    this.flowStateAccessor = userState.createProperty('flowState')
+  }
+
+  /**
+   * Gets the OAuth token.
+   * @param context The turn context.
+   * @returns A promise that resolves to the user token.
+   */
+  public async getOAuthToken (context: TurnContext) : Promise<string> {
+    this.state = await this.getUserState(context)
+    if (this.state!.userToken !== '') {
+      return this.state.userToken
+    }
+    if (this.state?.flowExpires !== 0 && Date.now() > this.state.flowExpires) {
+      logger.warn('Sign-in flow expired')
+      this.state.flowStarted = false
+      this.state.userToken = ''
+      await context.sendActivity(MessageFactory.text('Sign-in session expired. Please try again.'))
+    }
+
+    let retVal: string = ''
+    const authConfig = context.adapter.authConfig
+    if (authConfig.connectionName === undefined) {
+      throw new Error('connectionName is not set in the auth config, review your environment variables')
+    }
+    const adapter = context.adapter as CloudAdapter
+    const scope = 'https://api.botframework.com'
+    const accessToken = await adapter.authProvider.getAccessToken(authConfig, scope)
+    this.userTokenClient = new UserTokenClient(accessToken)
+
+    if (this.state!.flowStarted === true) {
+      const userToken = await this.userTokenClient.getUserToken(authConfig.connectionName!, context.activity.channelId!, context.activity.from?.id!)
+      if (userToken !== null) {
+        logger.info('Token obtained')
+        this.state.userToken = userToken.token
+        this.state.flowStarted = false
+      } else {
+        const code = context.activity.text as string
+        const userToken = await this.userTokenClient!.getUserToken(authConfig.connectionName!, context.activity.channelId!, context.activity.from?.id!, code)
+        if (userToken !== null) {
+          logger.info('Token obtained with code')
+          this.state.userToken = userToken.token
+          this.state.flowStarted = false
+        } else {
+          logger.error('Sign in failed')
+          await context.sendActivity(MessageFactory.text('Sign in failed'))
+        }
+      }
+      retVal = this.state.userToken
+    } else if (this.state!.flowStarted === false) {
+      const signingResource = await this.userTokenClient.getSignInResource(authConfig.clientId!, authConfig.connectionName!, context.activity)
+      const oCard: Attachment = CardFactory.oauthCard(authConfig.connectionName!, 'Sign in', '', signingResource)
+      await context.sendActivity(MessageFactory.attachment(oCard))
+      this.state!.flowStarted = true
+      this.state.flowExpires = Date.now() + 30000
+      logger.info('OAuth flow started')
+    }
+    this.flowStateAccessor.set(context, this.state)
+    return retVal
+  }
+
+  /**
+   * Signs the user out.
+   * @param context The turn context.
+   * @returns A promise that resolves when the sign-out operation is complete.
+   */
+  async signOut (context: TurnContext) {
+    await this.userTokenClient!.signOut(context.activity.from?.id!, context.adapter.authConfig.connectionName!, context.activity.channelId!)
+    this.state!.flowStarted = false
+    this.state!.userToken = ''
+    this.state!.flowExpires = 0
+    this.flowStateAccessor.set(context, this.state)
+    logger.info('User signed out successfully')
+  }
+
+  /**
+   * Gets the user state.
+   * @param context The turn context.
+   * @returns A promise that resolves to the user state.
+   */
+  private async getUserState (context: TurnContext) {
+    let userProfile: FlowState | null = await this.flowStateAccessor.get(context, null)
+    if (userProfile === null) {
+      userProfile = new FlowState()
+    }
+    return userProfile
+  }
+}