@microsoft/agents-hosting 0.1.49

package/src/auth/msalTokenProvider.ts

@@ -0,0 +1,202 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ConfidentialClientApplication, LogLevel, ManagedIdentityApplication, NodeSystemOptions } from '@azure/msal-node'
+import { AuthConfiguration } from './authConfiguration'
+import { AuthProvider } from './authProvider'
+import { debug } from '../logger'
+import { v4 } from 'uuid'
+
+import fs from 'fs'
+import crypto from 'crypto'
+
+const audience = 'api://AzureADTokenExchange'
+const logger = debug('agents:msal-token-provider')
+
+/**
+ * Provides tokens using MSAL.
+ */
+export class MsalTokenProvider implements AuthProvider {
+  /**
+   * Gets an access token.
+   * @param authConfig The authentication configuration.
+   * @param scope The scope for the token.
+   * @returns A promise that resolves to the access token.
+   */
+  async getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string> {
+    if (!authConfig.clientId && process.env.NODE_ENV !== 'production') {
+      return ''
+    }
+    let token
+    if (authConfig.FICClientId !== undefined) {
+      token = await this.acquireAccessTokenViaFIC(authConfig, scope)
+    } else if (authConfig.clientSecret !== undefined) {
+      token = await this.acquireAccessTokenViaSecret(authConfig, scope)
+    } else if (authConfig.certPemFile !== undefined &&
+      authConfig.certKeyFile !== undefined) {
+      token = await this.acquireTokenWithCertificate(authConfig, scope)
+    } else if (authConfig.clientSecret === undefined &&
+      authConfig.certPemFile === undefined &&
+      authConfig.certKeyFile === undefined) {
+      token = await this.acquireTokenWithUserAssignedIdentity(authConfig, scope)
+    } else {
+      throw new Error('Invalid authConfig. ')
+    }
+    if (token === undefined) {
+      throw new Error('Failed to acquire token')
+    }
+
+    return token
+  }
+
+  private readonly sysOptions: NodeSystemOptions = {
+    loggerOptions: {
+      logLevel: LogLevel.Trace,
+      loggerCallback: (level, message, containsPii) => {
+        if (containsPii) {
+          return
+        }
+        switch (level) {
+          case LogLevel.Error:
+            logger.error(message)
+            return
+          case LogLevel.Info:
+            logger.info(message)
+            return
+          case LogLevel.Warning:
+            logger.warn(message)
+            return
+          case LogLevel.Verbose:
+            logger.debug(message)
+        }
+      },
+      piiLoggingEnabled: false
+    }
+  }
+
+  /**
+   * Acquires a token using a user-assigned identity.
+   * @param authConfig The authentication configuration.
+   * @param scope The scope for the token.
+   * @returns A promise that resolves to the access token.
+   */
+  private async acquireTokenWithUserAssignedIdentity (authConfig: AuthConfiguration, scope: string) {
+    const mia = new ManagedIdentityApplication({
+      managedIdentityIdParams: {
+        userAssignedClientId: authConfig.clientId || ''
+      },
+      system: this.sysOptions
+    })
+    const token = await mia.acquireToken({
+      resource: scope
+    })
+    return token?.accessToken
+  }
+
+  /**
+   * Acquires a token using a certificate.
+   * @param authConfig The authentication configuration.
+   * @param scope The scope for the token.
+   * @returns A promise that resolves to the access token.
+   */
+  private async acquireTokenWithCertificate (authConfig: AuthConfiguration, scope: string) {
+    const privateKeySource = fs.readFileSync(authConfig.certKeyFile as string)
+
+    const privateKeyObject = crypto.createPrivateKey({
+      key: privateKeySource,
+      format: 'pem'
+    })
+
+    const privateKey = privateKeyObject.export({
+      format: 'pem',
+      type: 'pkcs8'
+    })
+
+    const pubKeyObject = new crypto.X509Certificate(fs.readFileSync(authConfig.certPemFile as string))
+
+    const cca = new ConfidentialClientApplication({
+      auth: {
+        clientId: authConfig.clientId || '',
+        authority: `https://login.microsoftonline.com/${authConfig.tenantId || 'botframework.com'}`,
+        clientCertificate: {
+          privateKey: privateKey as string,
+          thumbprint: pubKeyObject.fingerprint.replaceAll(':', ''),
+          x5c: Buffer.from(authConfig.certPemFile as string, 'base64').toString()
+        }
+      },
+      system: this.sysOptions
+    })
+    const token = await cca.acquireTokenByClientCredential({
+      scopes: [`${scope}/.default`],
+      correlationId: v4()
+    })
+    return token?.accessToken as string
+  }
+
+  /**
+   * Acquires a token using a client secret.
+   * @param authConfig The authentication configuration.
+   * @param scope The scope for the token.
+   * @returns A promise that resolves to the access token.
+   */
+  private async acquireAccessTokenViaSecret (authConfig: AuthConfiguration, scope: string) {
+    const cca = new ConfidentialClientApplication({
+      auth: {
+        clientId: authConfig.clientId as string,
+        authority: `https://login.microsoftonline.com/${authConfig.tenantId || 'botframework.com'}`,
+        clientSecret: authConfig.clientSecret
+      },
+      system: this.sysOptions
+    })
+    const token = await cca.acquireTokenByClientCredential({
+      scopes: [`${scope}/.default`],
+      correlationId: v4()
+    })
+    return token?.accessToken as string
+  }
+
+  /**
+   * Acquires a token using a FIC client assertion.
+   * @param authConfig The authentication configuration.
+   * @param scope The scope for the token.
+   * @returns A promise that resolves to the access token.
+   */
+  private async acquireAccessTokenViaFIC (authConfig: AuthConfiguration, scope: string) : Promise<string> {
+    const scopes = [`${scope}/.default`]
+    const clientAssertion = await this.fetchExternalToken(authConfig.FICClientId as string)
+    const cca = new ConfidentialClientApplication({
+      auth: {
+        clientId: authConfig.clientId as string,
+        authority: `https://login.microsoftonline.com/${authConfig.tenantId}`,
+        clientAssertion
+      },
+      system: this.sysOptions
+    })
+    const token = await cca.acquireTokenByClientCredential({ scopes })
+    logger.info('got token using FIC client assertion')
+    return token?.accessToken as string
+  }
+
+  /**
+   * Fetches an external token.
+   * @param FICClientId The FIC client ID.
+   * @returns A promise that resolves to the external token.
+   */
+  private async fetchExternalToken (FICClientId: string) : Promise<string> {
+    const managedIdentityClientAssertion = new ManagedIdentityApplication({
+      managedIdentityIdParams: {
+        userAssignedClientId: FICClientId
+      },
+      system: this.sysOptions
+    }
+    )
+    const response = await managedIdentityClientAssertion.acquireToken({
+      resource: audience,
+      forceRefresh: true
+    })
+    logger.info('got token for FIC')
+    return response.accessToken
+  }
+}

package/src/auth/request.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { JwtPayload } from 'jsonwebtoken'
+
+/**
+ * Represents a Node.js HTTP Request, including the minimal set of use properties.
+ * Compatible with Restify, Express, and Node.js core http.
+ */
+export interface Request<
+    Body extends Record<string, unknown> = Record<string, unknown>,
+    Headers extends Record<string, string[] | string | undefined> = Record<string, string[] | string | undefined>
+> {
+  body?: Body
+  headers: Headers
+  method?: string
+  user?: JwtPayload
+}

package/src/baseAdapter.ts

@@ -0,0 +1,174 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthConfiguration } from './auth/authConfiguration'
+import { AuthProvider } from './auth/authProvider'
+import { MsalTokenProvider } from './auth/msalTokenProvider'
+import { Middleware, MiddlewareHandler, MiddlewareSet } from './middlewareSet'
+import { TurnContext } from './turnContext'
+import { debug } from './logger'
+import { Activity, ConversationReference } from '@microsoft/agents-activity'
+import { ResourceResponse } from './connector-client/resourceResponse'
+import { AttachmentData } from './connector-client/attachmentData'
+import { AttachmentInfo } from './connector-client/attachmentInfo'
+
+const logger = debug('agents:base-adapter')
+
+/**
+ * Base class for all adapters, providing middleware and error handling capabilities.
+ */
+export abstract class BaseAdapter {
+  protected middleware: MiddlewareSet = new MiddlewareSet()
+
+  private turnError: (context: TurnContext, error: Error) => Promise<void> = async (context: TurnContext, error: Error) => {
+    logger.error(`\n [onTurnError] unhandled error: ${error}`)
+
+    // Send a trace activity, which will be displayed in Bot Framework Emulator
+    await context.sendTraceActivity(
+      'OnTurnError Trace',
+      `${error}`,
+      'https://www.botframework.com/schemas/error',
+      'TurnError'
+    )
+
+    // Send a message to the user
+    await context.sendActivity('The agent encountered an error or bug.')
+    await context.sendActivity('To continue to run this agent, please fix the source code.')
+  }
+
+  readonly AgentIdentityKey = Symbol('AgentIdentity')
+  readonly ConnectorClientKey = Symbol('ConnectorClient')
+  readonly OAuthScopeKey = Symbol('OAuthScope')
+
+  authProvider: AuthProvider = new MsalTokenProvider()
+  authConfig: AuthConfiguration = { issuers: [] }
+
+  /**
+   * Sends a set of activities to the conversation.
+   * @param context - The TurnContext for the current turn.
+   * @param activities - The activities to send.
+   * @returns A promise representing the array of ResourceResponses for the sent activities.
+   */
+  abstract sendActivities (context: TurnContext, activities: Activity[]): Promise<ResourceResponse[]>
+
+  /**
+   * Updates an existing activity.
+   * @param context - The TurnContext for the current turn.
+   * @param activity - The activity to update.
+   * @returns A promise representing the ResourceResponse for the updated activity.
+   */
+  abstract updateActivity (context: TurnContext, activity: Activity): Promise<ResourceResponse | void>
+
+  /**
+   * Deletes an existing activity.
+   * @param context - The TurnContext for the current turn.
+   * @param reference - The conversation reference of the activity to delete.
+   * @returns A promise representing the completion of the delete operation.
+   */
+  abstract deleteActivity (context: TurnContext, reference: Partial<ConversationReference>): Promise<void>
+
+  /**
+   * Continues a conversation.
+   * @param reference - The conversation reference to continue.
+   * @param logic - The logic to execute.
+   * @returns A promise representing the completion of the continue operation.
+   */
+  abstract continueConversation (
+    reference: Partial<ConversationReference>,
+    logic: (revocableContext: TurnContext) => Promise<void>
+  ): Promise<void>
+
+  /**
+   * Uploads an attachment.
+   * @param conversationId - The conversation ID.
+   * @param attachmentData - The attachment data.
+   * @returns A promise representing the ResourceResponse for the uploaded attachment.
+   */
+  abstract uploadAttachment (conversationId: string, attachmentData: AttachmentData): Promise<ResourceResponse>
+
+  /**
+   * Gets attachment information.
+   * @param attachmentId - The attachment ID.
+   * @returns A promise representing the AttachmentInfo for the requested attachment.
+   */
+  abstract getAttachmentInfo (attachmentId: string): Promise<AttachmentInfo>
+
+  /**
+   * Gets an attachment.
+   * @param attachmentId - The attachment ID.
+   * @param viewId - The view ID.
+   * @returns A promise representing the NodeJS.ReadableStream for the requested attachment.
+   */
+  abstract getAttachment (attachmentId: string, viewId: string): Promise<NodeJS.ReadableStream>
+
+  get onTurnError (): (context: TurnContext, error: Error) => Promise<void> {
+    return this.turnError
+  }
+
+  set onTurnError (value: (context: TurnContext, error: Error) => Promise<void>) {
+    this.turnError = value
+  }
+
+  /**
+   * Adds middleware to the adapter's middleware pipeline.
+   * @param middlewares - The middleware to add.
+   * @returns The adapter instance.
+   */
+  use (...middlewares: Array<MiddlewareHandler | Middleware>): this {
+    this.middleware.use(...middlewares)
+
+    return this
+  }
+
+  private makeRevocable<T extends Record<string, any>>(
+    target: T,
+    handler?: ProxyHandler<T>
+  ): { proxy: T, revoke: () => void } {
+    // Ensure proxy supported (some browsers don't)
+    if (typeof Proxy !== 'undefined' && Proxy.revocable) {
+      return Proxy.revocable(target, (handler != null) ? handler : {})
+    } else {
+      return {
+        proxy: target,
+        revoke: (): void => {
+          // noop
+        }
+      }
+    }
+  }
+
+  /**
+   * Runs the middleware pipeline in sequence.
+   * @param context - The TurnContext for the current turn.
+   * @param next - The next function to call in the pipeline.
+   * @returns A promise representing the completion of the middleware pipeline.
+   */
+  protected async runMiddleware (
+    context: TurnContext,
+    next: (revocableContext: TurnContext) => Promise<void>
+  ): Promise<void> {
+    if (context && context.activity && context.activity.locale) {
+      context.locale = context.activity.locale
+    }
+
+    const pContext = this.makeRevocable(context)
+
+    try {
+      await this.middleware.run(pContext.proxy, async () => await next(pContext.proxy))
+    } catch (err) {
+      if (this.onTurnError) {
+        if (err instanceof Error) {
+          await this.onTurnError(pContext.proxy, err)
+        } else {
+          throw new Error('Unknown error type')
+        }
+      } else {
+        throw err
+      }
+    } finally {
+      pContext.revoke()
+    }
+  }
+}

package/src/cards/animationCard.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CardAction } from '@microsoft/agents-activity'
+import { MediaUrl } from './mediaUrl'
+import { ThumbnailUrl } from './thumbnailUrl'
+
+/**
+ * Interface representing an Animation Card.
+ */
+export interface AnimationCard {
+  /** The title of the card. */
+  title: string
+  /** The subtitle of the card. */
+  subtitle: string
+  /** The text content of the card. */
+  text: string
+  /** The image to be displayed on the card. */
+  image: ThumbnailUrl
+  /** The media URLs or objects. */
+  media: MediaUrl[]
+  /** The buttons to be displayed on the card. */
+  buttons: CardAction[]
+  /** Indicates whether the card is shareable. */
+  shareable: boolean
+  /** Indicates whether the card should auto-loop. */
+  autoloop: boolean
+  /** Indicates whether the card should auto-start. */
+  autostart: boolean
+  /** The aspect ratio of the card. */
+  aspect: string
+  /** The duration of the animation. */
+  duration: string
+  /** Additional value for the card. */
+  value: any
+}

package/src/cards/audioCard.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright(c) Microsoft Corporation.All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CardAction } from '@microsoft/agents-activity'
+import { MediaUrl } from './mediaUrl'
+import { ThumbnailUrl } from './thumbnailUrl'
+
+/**
+ * Interface representing an Audio Card.
+ */
+export interface AudioCard {
+  /** The title of the card. */
+  title: string
+  /** The subtitle of the card. */
+  subtitle: string
+  /** The text content of the card. */
+  text: string
+  /** The image to be displayed on the card. */
+  image: ThumbnailUrl
+  /** The media URLs or objects. */
+  media: MediaUrl[]
+  /** The buttons to be displayed on the card. */
+  buttons: CardAction[]
+  /** Indicates whether the card is shareable. */
+  shareable: boolean
+  /** Indicates whether the card should auto-loop. */
+  autoloop: boolean
+  /** Indicates whether the card should auto-start. */
+  autostart: boolean
+  /** The aspect ratio of the card. */
+  aspect: string
+  /** The duration of the audio. */
+  duration: string
+  /** Additional value for the card. */
+  value: any
+}