@microsoft/agents-hosting 0.1.49

package/src/app/oauth/webChatOAuthFlowAppStyle.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { Attachment } from '@microsoft/agents-activity'
+import { UserTokenClient } from '../../oauth/userTokenClient'
+import { CloudAdapter } from '../../cloudAdapter'
+import { CardFactory } from '../../cards/cardFactory'
+import { TurnContext } from '../../turnContext'
+import { MessageFactory } from '../../messageFactory'
+import { debug } from '../../logger'
+import { TurnState } from '../turnState'
+import { Storage } from '../../storage'
+
+const logger = debug('agents:web-chat-oauth-flow')
+
+export class WebChatOAuthFlowAppStyle {
+  userTokenClient?: UserTokenClient
+  storage: Storage
+
+  constructor (storage: Storage) {
+    this.storage = storage
+  }
+
+  public async getOAuthToken (context: TurnContext, state: TurnState) : Promise<string> {
+    if (Object.keys(state.sso).length === 0) {
+      state.sso.flowStarted = false
+      state.sso.userToken = ''
+      state.sso.flowExpires = 0
+      await state.save(context)
+    }
+    if (state.sso!.userToken !== '') {
+      return state.sso.userToken
+    }
+    if (state.sso?.flowExpires !== 0 && Date.now() > state.sso.flowExpires) {
+      logger.warn('Sign-in flow expired')
+      state.sso.flowStarted = false
+      state.sso.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 (state.sso!.flowStarted === true) {
+      const userToken = await this.userTokenClient.getUserToken(authConfig.connectionName!, context.activity.channelId!, context.activity.from?.id!)
+      if (userToken !== null) {
+        logger.info('Token obtained')
+        state.sso.userToken = userToken.token
+        state.sso.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')
+          state.sso.userToken = userToken.token
+          state.sso.flowStarted = false
+        } else {
+          logger.error('Sign in failed')
+          await context.sendActivity(MessageFactory.text('Sign in failed'))
+        }
+      }
+      retVal = state.sso.userToken
+    } else if (state.sso!.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))
+      state.sso!.flowStarted = true
+      state.sso.flowExpires = Date.now() + 30000
+      logger.info('OAuth flow started')
+    }
+    state.save(context)
+    return retVal
+  }
+
+  async signOut (context: TurnContext, state: TurnState) {
+    await this.userTokenClient!.signOut(context.activity.from?.id!, context.adapter.authConfig.connectionName!, context.activity.channelId!)
+    state.sso!.flowStarted = false
+    state.sso!.userToken = ''
+    state.sso!.flowExpires = 0
+    state.save(context)
+    logger.info('User signed out successfully')
+  }
+}

package/src/app/routeHandler.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TurnContext } from '../turnContext'
+import { TurnState } from './turnState'
+
+export type RouteHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<void>

package/src/app/routeSelector.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TurnContext } from '../turnContext'
+
+export type Selector = (context: TurnContext) => Promise<boolean>
+
+export type RouteSelector = Selector

package/src/app/turnEvents.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export type TurnEvents = 'beforeTurn' | 'afterTurn'

package/src/app/turnState.ts

@@ -0,0 +1,338 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Storage, StoreItems } from '../storage'
+import { Memory } from './memory'
+import { InputFile } from './inputFileDownloader'
+import { TurnStateEntry } from './turnStateEntry'
+import { TurnContext } from '../turnContext'
+import { debug } from '../logger'
+
+const logger = debug('agents:turnState')
+
+const CONVERSATION_SCOPE = 'conversation'
+
+const USER_SCOPE = 'user'
+
+const TEMP_SCOPE = 'temp'
+
+const SSO_SCOPE = 'sso'
+
+export interface DefaultConversationState {}
+
+export interface DefaultUserState {}
+export interface DefaultTempState {
+  input: string;
+  inputFiles: InputFile[];
+  lastOutput: string;
+  actionOutputs: Record<string, string>;
+  authTokens: { [key: string]: string };
+  duplicateTokenExchange?: boolean;
+}
+
+export interface DefaultSSOState {
+  flowStarted: boolean;
+  userToken: string;
+  flowExpires: number;
+}
+
+/**
+ * Base class defining a collection of turn state scopes.
+ * @remarks
+ * Developers can create a derived class that extends `TurnState` to add additional state scopes.
+ * ```JavaScript
+ * class MyTurnState extends TurnState {
+ *   protected async onComputeStorageKeys(context) {
+ *     const keys = await super.onComputeStorageKeys(context);
+ *     keys['myScope'] = `myScopeKey`;
+ *     return keys;
+ *   }
+ *
+ *   public get myScope() {
+ *     const scope = this.getScope('myScope');
+ *     if (!scope) {
+ *       throw new Error(`MyTurnState hasn't been loaded. Call load() first.`);
+ *     }
+ *     return scope.value;
+ *   }
+ *
+ *   public set myScope(value) {
+ *     const scope = this.getScope('myScope');
+ *     if (!scope) {
+ *       throw new Error(`MyTurnState hasn't been loaded. Call load() first.`);
+ *     }
+ *     scope.replace(value);
+ *   }
+ * }
+ * ```
+ */
+
+export class TurnState<
+    TConversationState = DefaultConversationState,
+    TUserState = DefaultUserState,
+    TTempState = DefaultTempState,
+    TSSOState = DefaultSSOState
+> implements Memory {
+  private _scopes: Record<string, TurnStateEntry> = {}
+  private _isLoaded = false
+  private _loadingPromise?: Promise<boolean>
+  private _stateNotLoadedString = 'TurnState hasn\'t been loaded. Call load() first.'
+
+  public get conversation (): TConversationState {
+    const scope = this.getScope(CONVERSATION_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    return scope.value as TConversationState
+  }
+
+  public set conversation (value: TConversationState) {
+    const scope = this.getScope(CONVERSATION_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    scope.replace(value as Record<string, unknown>)
+  }
+
+  public get isLoaded (): boolean {
+    return this._isLoaded
+  }
+
+  public get temp (): TTempState {
+    const scope = this.getScope(TEMP_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    return scope.value as TTempState
+  }
+
+  public set temp (value: TTempState) {
+    const scope = this.getScope(TEMP_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    scope.replace(value as Record<string, unknown>)
+  }
+
+  public get user (): TUserState {
+    const scope = this.getScope(USER_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    return scope.value as TUserState
+  }
+
+  public set user (value: TUserState) {
+    const scope = this.getScope(USER_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    scope.replace(value as Record<string, unknown>)
+  }
+
+  public get sso (): TSSOState {
+    const scope = this.getScope(SSO_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    return scope.value as TSSOState
+  }
+
+  public set sso (value: TSSOState) {
+    const scope = this.getScope(SSO_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    scope.replace(value as Record<string, unknown>)
+  }
+
+  public deleteConversationState (): void {
+    const scope = this.getScope(CONVERSATION_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    scope.delete()
+  }
+
+  public deleteTempState (): void {
+    const scope = this.getScope(TEMP_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    scope.delete()
+  }
+
+  public deleteUserState (): void {
+    const scope = this.getScope(USER_SCOPE)
+    if (!scope) {
+      throw new Error(this._stateNotLoadedString)
+    }
+    scope.delete()
+  }
+
+  public getScope (scope: string): TurnStateEntry | undefined {
+    return this._scopes[scope]
+  }
+
+  public deleteValue (path: string): void {
+    const { scope, name } = this.getScopeAndName(path)
+    if (Object.prototype.hasOwnProperty.call(scope.value, name)) {
+      delete scope.value[name]
+    }
+  }
+
+  public hasValue (path: string): boolean {
+    const { scope, name } = this.getScopeAndName(path)
+    return Object.prototype.hasOwnProperty.call(scope.value, name)
+  }
+
+  public getValue<TValue = unknown>(path: string): TValue {
+    const { scope, name } = this.getScopeAndName(path)
+    return scope.value[name] as TValue
+  }
+
+  public setValue (path: string, value: unknown): void {
+    const { scope, name } = this.getScopeAndName(path)
+    scope.value[name] = value
+  }
+
+  public load (context: TurnContext, storage?: Storage): Promise<boolean> {
+    if (this._isLoaded) {
+      return Promise.resolve(false)
+    }
+
+    if (!this._loadingPromise) {
+      this._loadingPromise = new Promise<boolean>((resolve, reject) => {
+        this._isLoaded = true
+
+        const keys: string[] = []
+        this.onComputeStorageKeys(context)
+          .then(async (scopes) => {
+            for (const key in scopes) {
+              if (Object.prototype.hasOwnProperty.call(scopes, key)) {
+                keys.push(scopes[key])
+              }
+            }
+
+            const items = storage ? await storage.read(keys) : {}
+
+            for (const key in scopes) {
+              if (Object.prototype.hasOwnProperty.call(scopes, key)) {
+                const storageKey = scopes[key]
+                const value = items[storageKey]
+                this._scopes[key] = new TurnStateEntry(value, storageKey)
+              }
+            }
+
+            this._scopes[TEMP_SCOPE] = new TurnStateEntry({})
+            this._isLoaded = true
+            this._loadingPromise = undefined
+            resolve(true)
+          })
+          .catch((err) => {
+            logger.error(err)
+            this._loadingPromise = undefined
+            reject(err)
+          })
+      })
+    }
+
+    return this._loadingPromise
+  }
+
+  public async save (context: TurnContext, storage?: Storage): Promise<void> {
+    if (!this._isLoaded && this._loadingPromise) {
+      await this._loadingPromise
+    }
+
+    if (!this._isLoaded) {
+      throw new Error(this._stateNotLoadedString)
+    }
+
+    let changes: StoreItems | undefined
+    let deletions: string[] | undefined
+    for (const key in this._scopes) {
+      if (!Object.prototype.hasOwnProperty.call(this._scopes, key)) {
+        continue
+      }
+      const entry = this._scopes[key]
+      if (entry.storageKey) {
+        if (entry.isDeleted) {
+          if (deletions) {
+            deletions.push(entry.storageKey)
+          } else {
+            deletions = [entry.storageKey]
+          }
+        } else if (entry.hasChanged) {
+          if (!changes) {
+            changes = {}
+          }
+
+          changes[entry.storageKey] = entry.value
+        }
+      }
+    }
+
+    if (storage) {
+      const promises: Promise<void>[] = []
+      if (changes) {
+        promises.push(storage.write(changes))
+      }
+
+      if (deletions) {
+        promises.push(storage.delete(deletions))
+      }
+
+      if (promises.length > 0) {
+        await Promise.all(promises)
+      }
+    }
+  }
+
+  protected onComputeStorageKeys (context: TurnContext): Promise<Record<string, string>> {
+    const activity = context.activity
+    const channelId = activity?.channelId
+    const agentId = activity?.recipient?.id
+    const conversationId = activity?.conversation?.id
+    const userId = activity?.from?.id
+
+    if (!channelId) {
+      throw new Error('missing context.activity.channelId')
+    }
+
+    if (!agentId) {
+      throw new Error('missing context.activity.recipient.id')
+    }
+
+    if (!conversationId) {
+      throw new Error('missing context.activity.conversation.id')
+    }
+
+    if (!userId) {
+      throw new Error('missing context.activity.from.id')
+    }
+
+    const keys: Record<string, string> = {}
+    keys[CONVERSATION_SCOPE] = `${channelId}/${agentId}/conversations/${conversationId}`
+    keys[USER_SCOPE] = `${channelId}/${agentId}/users/${userId}`
+    keys[SSO_SCOPE] = `${channelId}/${agentId}/sso`
+    return Promise.resolve(keys)
+  }
+
+  private getScopeAndName (path: string): { scope: TurnStateEntry; name: string } {
+    const parts = path.split('.')
+    if (parts.length > 2) {
+      throw new Error(`Invalid state path: ${path}`)
+    } else if (parts.length === 1) {
+      parts.unshift(TEMP_SCOPE)
+    }
+
+    const scope = this.getScope(parts[0])
+    if (scope === undefined) {
+      throw new Error(`Invalid state scope: ${parts[0]}`)
+    }
+    return { scope, name: parts[1] }
+  }
+}

package/src/app/turnStateEntry.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export class TurnStateEntry {
+  private _value: Record<string, unknown>
+  private _storageKey?: string
+  private _deleted = false
+  private _hash: string
+
+  public constructor (value?: Record<string, unknown>, storageKey?: string) {
+    this._value = value || {}
+    this._storageKey = storageKey
+    this._hash = JSON.stringify(this._value)
+  }
+
+  public get hasChanged (): boolean {
+    return JSON.stringify(this._value) !== this._hash
+  }
+
+  public get isDeleted (): boolean {
+    return this._deleted
+  }
+
+  public get value (): Record<string, unknown> {
+    if (this.isDeleted) {
+      this._value = {}
+      this._deleted = false
+    }
+
+    return this._value
+  }
+
+  public get storageKey (): string | undefined {
+    return this._storageKey
+  }
+
+  public delete (): void {
+    this._deleted = true
+  }
+
+  public replace (value?: Record<string, unknown>): void {
+    this._value = value || {}
+  }
+}

package/src/auth/authConfiguration.ts

@@ -0,0 +1,68 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Represents the authentication configuration.
+ */
+export interface AuthConfiguration {
+  tenantId?: string
+  clientId?: string
+  clientSecret?: string
+  certPemFile?: string
+  certKeyFile?: string
+  issuers: string[]
+  connectionName?: string,
+  FICClientId?: string
+}
+
+/**
+ * Loads the authentication configuration from environment variables.
+ * @returns The authentication configuration.
+ * @throws Will throw an error if clientId is not provided in production.
+ */
+export const loadAuthConfigFromEnv: () => AuthConfiguration = () => {
+  if (process.env.clientId === undefined && process.env.NODE_ENV === 'production') {
+    throw new Error('ClientId required in production')
+  }
+  return {
+    tenantId: process.env.tenantId,
+    clientId: process.env.clientId,
+    clientSecret: process.env.clientSecret,
+    certPemFile: process.env.certPemFile,
+    certKeyFile: process.env.certKeyFile,
+    connectionName: process.env.connectionName,
+    FICClientId: process.env.FICClientId,
+    issuers: [
+      'https://api.botframework.com',
+      `https://sts.windows.net/${process.env.tenantId}/`,
+      `https://login.microsoftonline.com/${process.env.tenantId}/v2.0`
+    ]
+  }
+}
+
+/**
+ * Loads the agent authentication configuration from environment variables.
+ * @returns The agent authentication configuration.
+ * @throws Will throw an error if MicrosoftAppId is not provided in production.
+ */
+export const loadBotAuthConfigFromEnv: () => AuthConfiguration = () => {
+  if (process.env.MicrosoftAppId === undefined && process.env.NODE_ENV === 'production') {
+    throw new Error('ClientId required in production')
+  }
+  return {
+    tenantId: process.env.MicrosoftAppTenantId,
+    clientId: process.env.MicrosoftAppId,
+    clientSecret: process.env.MicrosoftAppPassword,
+    certPemFile: process.env.certPemFile,
+    certKeyFile: process.env.certKeyFile,
+    connectionName: process.env.connectionName,
+    FICClientId: process.env.MicrosoftAppClientId,
+    issuers: [
+      'https://api.botframework.com',
+        `https://sts.windows.net/${process.env.MicrosoftAppTenantId}/`,
+        `https://login.microsoftonline.com/${process.env.MicrosoftAppTenantId}/v2.0`
+    ]
+  }
+}

package/src/auth/authProvider.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthConfiguration } from './authConfiguration'
+
+/**
+ * Interface representing an authentication provider.
+ */
+export interface AuthProvider {
+  /**
+   * Gets an access token for the specified authentication configuration and scope.
+   * @param authConfig - The authentication configuration.
+   * @param scope - The scope for which the access token is requested.
+   * @returns A promise that resolves to the access token.
+   */
+  getAccessToken: (authConfig: AuthConfiguration, scope: string) => Promise<string>
+}

package/src/auth/index.ts

@@ -0,0 +1,4 @@
+export * from './authConfiguration'
+export * from './authProvider'
+export * from './msalTokenProvider'
+export * from './request'

package/src/auth/jwt-middleware.ts

@@ -0,0 +1,99 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthConfiguration } from './authConfiguration'
+import { Response, NextFunction } from 'express'
+import { Request } from './request'
+import jwksRsa, { JwksClient, SigningKey } from 'jwks-rsa'
+import jwt, { JwtHeader, JwtPayload, SignCallback, GetPublicKeyOrSecret } from 'jsonwebtoken'
+import { debug } from '../logger'
+
+const logger = debug('agents:jwt-middleware')
+
+/**
+ * Verifies the JWT token.
+ * @param raw The raw JWT token.
+ * @param config The authentication configuration.
+ * @returns A promise that resolves to the JWT payload.
+ */
+const verifyToken = async (raw: string, config: AuthConfiguration): Promise<JwtPayload> => {
+  const getKey: GetPublicKeyOrSecret = (header: JwtHeader, callback: SignCallback) => {
+    const payload = jwt.decode(raw) as JwtPayload
+
+    const jwksUri: string = payload.iss === 'https://api.botframework.com'
+      ? 'https://login.botframework.com/v1/.well-known/keys'
+      : `https://login.microsoftonline.com/${config.tenantId}/discovery/v2.0/keys`
+
+    logger.info(`fetching keys from ${jwksUri}`)
+    const jwksClient: JwksClient = jwksRsa({ jwksUri })
+
+    jwksClient.getSigningKey(header.kid, (err: Error | null, key: SigningKey | undefined): void => {
+      if (err != null) {
+        logger.error('jwksClient.getSigningKey ', JSON.stringify(err))
+        logger.error(JSON.stringify(err))
+        callback(err, undefined)
+        return
+      }
+      const signingKey = key?.getPublicKey()
+      callback(null, signingKey)
+    })
+  }
+
+  return await new Promise((resolve, reject) => {
+    const verifyOptions: jwt.VerifyOptions = {
+      issuer: config.issuers,
+      audience: [config.clientId!, 'https://api.botframework.com'],
+      ignoreExpiration: false,
+      algorithms: ['RS256']
+    }
+
+    jwt.verify(raw, getKey, verifyOptions, (err, user) => {
+      if (err != null) {
+        logger.error('jwt.verify ', JSON.stringify(err))
+        reject(err)
+        return
+      }
+      const tokenClaims = user as JwtPayload
+
+      resolve(tokenClaims)
+    })
+  })
+}
+
+/**
+ * Middleware to authorize JWT tokens.
+ * @param authConfig The authentication configuration.
+ * @returns An Express middleware function.
+ */
+export const authorizeJWT = (authConfig: AuthConfiguration) => {
+  return async function (req: Request, res: Response, next: NextFunction) {
+    let failed = false
+    logger.info('authorizing jwt')
+    const authHeader = req.headers.authorization as string
+    if (authHeader) {
+      const token: string = authHeader.split(' ')[1] // Extract the token from the Bearer string
+      try {
+        const user = await verifyToken(token, authConfig)
+        logger.debug('token verified for ', user)
+        req.user = user
+      } catch (err: Error | any) {
+        failed = true
+        logger.error(err)
+        res.status(401).send({ 'jwt-auth-error': err.message })
+      }
+    } else {
+      if (!authConfig.clientId && process.env.NODE_ENV !== 'production') {
+        logger.info('using anonymous auth')
+        req.user = { name: 'anonymous' }
+      } else {
+        logger.error('authorization header not found')
+        res.status(401).send({ 'jwt-auth-error': 'authorization header not found' })
+      }
+    }
+    if (!failed) {
+      next()
+    }
+  }
+}