@microsoft/agents-hosting 1.1.0-alpha.9.g154c2c8a32 → 1.1.1

package/src/oauth/userTokenClient.ts

@@ -2,11 +2,14 @@
 // Licensed under the MIT License.
 
 import axios, { AxiosInstance } from 'axios'
-import { ConversationReference } from '@microsoft/agents-activity'
+import { Activity, ConversationReference } from '@microsoft/agents-activity'
 import { debug } from '@microsoft/agents-activity/logger'
 import { normalizeTokenExchangeState } from '../activityWireCompat'
 import { AadResourceUrls, SignInResource, TokenExchangeRequest, TokenOrSinginResourceResponse, TokenResponse, TokenStatus } from './userTokenClient.types'
 import { getProductInfo } from '../getProductInfo'
+import { AuthProvider, MsalTokenProvider } from '../auth'
+import { HeaderPropagationCollection } from '../headerPropagation'
+import { getTokenServiceEndpoint } from './customUserTokenAPI'
 
 const logger = debug('agents:user-token-client')
 
@@ -15,19 +18,31 @@ const logger = debug('agents:user-token-client')
  */
 export class UserTokenClient {
   client: AxiosInstance
+  private msAppId: string = ''
   /**
    * Creates a new instance of UserTokenClient.
    * @param msAppId The Microsoft application ID.
    */
-  constructor (private msAppId: string) {
-    const baseURL = 'https://api.botframework.com'
-    this.client = axios.create({
-      baseURL,
-      headers: {
-        Accept: 'application/json',
-        'User-Agent': getProductInfo(),
-      }
-    })
+  constructor (msAppId: string)
+  /**
+   * Creates a new instance of UserTokenClient.
+   * @param axiosInstance The axios instance.
+   */
+  constructor (axiosInstance: AxiosInstance)
+
+  constructor (param: string | AxiosInstance) {
+    if (typeof param === 'string') {
+      const baseURL = getTokenServiceEndpoint()
+      this.client = axios.create({
+        baseURL,
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': getProductInfo(),
+        }
+      })
+    } else {
+      this.client = param
+    }
 
     this.client.interceptors.request.use((config) => {
       const { method, url, data, headers, params } = config
@@ -79,15 +94,49 @@ export class UserTokenClient {
       })
   }
 
+  /**
+   * Creates a new instance of UserTokenClient with authentication.
+   * @param baseURL - The base URL for the API.
+   * @param authConfig - The authentication configuration.
+   * @param authProvider - The authentication provider.
+   * @param scope - The scope for the authentication token.
+   * @param headers - Optional headers to propagate in the request.
+   * @returns A new instance of ConnectorClient.
+   */
+  static async createClientWithScope (
+    baseURL: string,
+    authProvider: AuthProvider,
+    scope: string,
+    headers?: HeaderPropagationCollection
+  ): Promise<UserTokenClient> {
+    // TODO: add header propagation logic
+    const axiosInstance = axios.create({
+      baseURL,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json', // Required by transformRequest
+        'User-Agent': getProductInfo(),
+      },
+    })
+    if (authProvider) {
+      const token = await (authProvider as MsalTokenProvider).getAccessToken(scope)
+      if (token.length > 1) {
+        axiosInstance.defaults.headers.common.Authorization = `Bearer ${token}`
+      }
+    }
+    return new UserTokenClient(axiosInstance)
+  }
+
   /**
    * Gets the user token.
    * @param connectionName The connection name.
-   * @param channelId The channel ID.
+   * @param channelIdComposite 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) : Promise<TokenResponse> {
+  async getUserToken (connectionName: string, channelIdComposite: string, userId: string, code?: string) : Promise<TokenResponse> {
+    const [channelId] = Activity.parseChannelId(channelIdComposite)
     const params = { connectionName, channelId, userId, code }
     const response = await this.client.get('/api/usertoken/GetToken', { params })
     if (response?.data) {
@@ -100,10 +149,11 @@ export class UserTokenClient {
    * Signs the user out.
    * @param userId The user ID.
    * @param connectionName The connection name.
-   * @param channelId The channel ID.
+   * @param channelIdComposite The channel ID.
    * @returns A promise that resolves when the sign-out operation is complete.
    */
-  async signOut (userId: string, connectionName: string, channelId: string) : Promise<void> {
+  async signOut (userId: string, connectionName: string, channelIdComposite: string) : Promise<void> {
+    const [channelId] = Activity.parseChannelId(channelIdComposite)
     const params = { userId, connectionName, channelId }
     const response = await this.client.delete('/api/usertoken/SignOut', { params })
     if (response.status !== 200) {
@@ -137,11 +187,12 @@ export class UserTokenClient {
    * Exchanges the token.
    * @param userId The user ID.
    * @param connectionName The connection name.
-   * @param channelId The channel ID.
+   * @param channelIdComposite 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) : Promise<TokenResponse> {
+  async exchangeTokenAsync (userId: string, connectionName: string, channelIdComposite: string, tokenExchangeRequest: TokenExchangeRequest) : Promise<TokenResponse> {
+    const [channelId] = Activity.parseChannelId(channelIdComposite)
     const params = { userId, connectionName, channelId }
     const response = await this.client.post('/api/usertoken/exchange', tokenExchangeRequest, { params })
     if (response?.data) {
@@ -155,7 +206,7 @@ export class UserTokenClient {
    * Gets the token or sign-in resource.
    * @param userId The user ID.
    * @param connectionName The connection name.
-   * @param channelId The channel ID.
+   * @param channelIdComposite The channel ID.
    * @param conversation The conversation reference.
    * @param relatesTo The related conversation reference.
    * @param code The code.
@@ -163,7 +214,8 @@ export class UserTokenClient {
    * @param fwdUrl The forward URL.
    * @returns A promise that resolves to the token or sign-in resource response.
    */
-  async getTokenOrSignInResource (userId: string, connectionName: string, channelId: string, conversation: ConversationReference, relatesTo: ConversationReference, code: string, finalRedirect: string = '', fwdUrl: string = '') : Promise<TokenOrSinginResourceResponse> {
+  async getTokenOrSignInResource (userId: string, connectionName: string, channelIdComposite: string, conversation: ConversationReference, relatesTo: ConversationReference, code: string, finalRedirect: string = '', fwdUrl: string = '') : Promise<TokenOrSinginResourceResponse> {
+    const [channelId] = Activity.parseChannelId(channelIdComposite)
     const state = Buffer.from(JSON.stringify({ conversation, relatesTo, connectionName, msAppId: this.msAppId })).toString('base64')
     const params = { userId, connectionName, channelId, state, code, finalRedirect, fwdUrl }
     const response = await this.client.get('/api/usertoken/GetTokenOrSignInResource', { params })
@@ -173,11 +225,12 @@ export class UserTokenClient {
   /**
    * Gets the token status.
    * @param userId The user ID.
-   * @param channelId The channel ID.
+   * @param channelIdComposite The channel ID.
    * @param include The optional include parameter.
    * @returns A promise that resolves to the token status.
    */
-  async getTokenStatus (userId: string, channelId: string, include: string = null!): Promise<TokenStatus[]> {
+  async getTokenStatus (userId: string, channelIdComposite: string, include: string = null!): Promise<TokenStatus[]> {
+    const [channelId] = Activity.parseChannelId(channelIdComposite)
     const params = { userId, channelId, include }
     const response = await this.client.get('/api/usertoken/GetTokenStatus', { params })
     return response.data as TokenStatus[]
@@ -187,11 +240,12 @@ export class UserTokenClient {
    * Gets the AAD tokens.
    * @param userId The user ID.
    * @param connectionName The connection name.
-   * @param channelId The channel ID.
+   * @param channelIdComposite The channel ID.
    * @param resourceUrls The resource URLs.
    * @returns A promise that resolves to the AAD tokens.
    */
-  async getAadTokens (userId: string, connectionName: string, channelId: string, resourceUrls: AadResourceUrls) : Promise<Record<string, TokenResponse>> {
+  async getAadTokens (userId: string, connectionName: string, channelIdComposite: string, resourceUrls: AadResourceUrls) : Promise<Record<string, TokenResponse>> {
+    const [channelId] = Activity.parseChannelId(channelIdComposite)
     const params = { userId, connectionName, channelId }
     const response = await this.client.post('/api/usertoken/GetAadTokens', resourceUrls, { params })
     return response.data as Record<string, TokenResponse>

package/src/oauth/userTokenClient.types.ts

@@ -20,19 +20,31 @@ export interface TokenResponse {
  */
 export interface TokenExchangeRequest {
   /**
-     * The URI for the token exchange request.
-     */
+   * The URI for the token exchange request.
+   */
   uri?: string;
-
   /**
-     * The token to be exchanged.
-     */
+   * The token to be exchanged.
+   */
   token?: string;
+}
 
+/**
+ * Represents the response for a token exchange invoke operation.
+ */
+export interface TokenExchangeInvokeResponse {
   /**
-     * The ID associated with the token exchange request.
-     */
-  id?: string;
+   * The connection name associated with the token exchange response.
+   */
+  connectionName: string
+  /**
+   * The ID associated with the token exchange response.
+   */
+  id?: string
+  /**
+   * (Optional) Details about any failure that occurred during the token exchange.
+   */
+  failureDetail?: string
 }
 
 /**

package/src/transcript/fileTranscriptLogger.ts

@@ -0,0 +1,409 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { debug } from '@microsoft/agents-activity/logger'
+import { PagedResult, TranscriptInfo } from './transcriptLogger'
+import { TranscriptStore } from './transcriptStore'
+import * as fs from 'fs/promises'
+import * as path from 'path'
+import { EOL } from 'os'
+import { Activity, ActivityTypes } from '@microsoft/agents-activity'
+
+const logger = debug('agents:file-transcript-logger')
+
+/**
+ * FileTranscriptLogger which creates a .transcript file for each conversationId.
+ * @remarks
+ * This is a useful class for unit tests.
+ *
+ * Concurrency Safety:
+ * - Uses an in-memory promise chain to serialize writes within the same Node.js process
+ * - Prevents race conditions and file corruption when multiple concurrent writes occur
+ * - Optimized for performance with minimal overhead (no file-based locking)
+ *
+ * Note: This implementation is designed for single-process scenarios. For multi-server
+ * deployments, consider using a database-backed transcript store.
+ */
+export class FileTranscriptLogger implements TranscriptStore {
+  private static readonly TRANSCRIPT_FILE_EXTENSION = '.transcript'
+  private static readonly MAX_FILE_NAME_SIZE = 100
+  private readonly _folder: string
+  private readonly _fileLocks: Map<string, Promise<any>> = new Map()
+
+  /**
+   * Initializes a new instance of the FileTranscriptLogger class.
+   * @param folder - Folder to place the transcript files (Default current directory).
+   */
+  constructor (folder?: string) {
+    this._folder = path.normalize(folder ?? process.cwd())
+  }
+
+  /**
+   * Log an activity to the transcript.
+   * @param activity - The activity to transcribe.
+   * @returns A promise that represents the work queued to execute.
+   */
+  async logActivity (activity: Activity): Promise<void> {
+    if (!activity) {
+      throw new Error('activity is required.')
+    }
+
+    const transcriptFile = this.getTranscriptFile(activity.channelId!, activity.conversation?.id!)
+
+    if (activity.type === ActivityTypes.Message) {
+      const sender = activity.from?.name ?? activity.from?.id ?? activity.from?.role
+      logger.debug(`${sender} [${activity.type}] ${activity.text}`)
+    } else {
+      const sender = activity.from?.name ?? activity.from?.id ?? activity.from?.role
+      logger.debug(`${sender} [${activity.type}]`)
+    }
+
+    await this.withFileLock(transcriptFile, async () => {
+      const maxRetries = 3
+      for (let i = 1; i <= maxRetries; i++) {
+        try {
+          switch (activity.type) {
+            case ActivityTypes.MessageDelete:
+              return await this.messageDeleteAsync(activity, transcriptFile)
+
+            case ActivityTypes.MessageUpdate:
+              return await this.messageUpdateAsync(activity, transcriptFile)
+
+            default: // Append activity
+              return await this.logActivityToFile(activity, transcriptFile)
+          }
+        } catch (error) {
+          // Try again
+          logger.warn(`Try ${i} - Failed to log activity because:`, error)
+          if (i === maxRetries) {
+            throw error
+          }
+        }
+      }
+    })
+  }
+
+  /**
+   * Gets from the store activities that match a set of criteria.
+   * @param channelId - The ID of the channel the conversation is in.
+   * @param conversationId - The ID of the conversation.
+   * @param continuationToken - The continuation token (if available).
+   * @param startDate - A cutoff date. Activities older than this date are not included.
+   * @returns A promise that resolves with the matching activities.
+   */
+  async getTranscriptActivities (
+    channelId: string,
+    conversationId: string,
+    continuationToken?: string,
+    startDate?: Date
+  ): Promise<PagedResult<Activity>> {
+    const transcriptFile = this.getTranscriptFile(channelId, conversationId)
+    if (!await this.pathExists(transcriptFile)) {
+      logger.debug(`Transcript file does not exist: ${this.protocol(transcriptFile)}`)
+      return { items: [], continuationToken: undefined }
+    }
+
+    const transcript = await this.loadTranscriptAsync(transcriptFile)
+    const filterDate = startDate ?? new Date(0)
+    const items = transcript.filter(activity => {
+      const activityDate = activity.timestamp ? new Date(activity.timestamp) : new Date(0)
+      return activityDate >= filterDate
+    })
+
+    return { items, continuationToken: undefined }
+  }
+
+  /**
+   * Gets the conversations on a channel from the store.
+   * @param channelId - The ID of the channel.
+   * @param continuationToken - Continuation token (if available).
+   * @returns A promise that resolves with all transcripts for the given ChannelID.
+   */
+  async listTranscripts (channelId: string, continuationToken?: string): Promise<PagedResult<TranscriptInfo>> {
+    const channelFolder = this.getChannelFolder(channelId)
+    if (!await this.pathExists(channelFolder)) {
+      logger.debug(`Channel folder does not exist: ${this.protocol(channelFolder)}`)
+      return { items: [], continuationToken: undefined }
+    }
+
+    const files = await fs.readdir(channelFolder)
+    const items: TranscriptInfo[] = []
+    for (const file of files) {
+      if (!file.endsWith('.transcript')) {
+        continue
+      }
+
+      const filePath = path.join(channelFolder, file)
+      const stats = await fs.stat(filePath)
+
+      items.push({
+        channelId,
+        id: path.parse(file).name,
+        created: stats.birthtime
+      })
+    }
+
+    return { items, continuationToken: undefined }
+  }
+
+  /**
+   * Deletes conversation data from the store.
+   * @param channelId - The ID of the channel the conversation is in.
+   * @param conversationId - The ID of the conversation to delete.
+   * @returns A promise that represents the work queued to execute.
+   */
+  async deleteTranscript (channelId: string, conversationId: string): Promise<void> {
+    const file = this.getTranscriptFile(channelId, conversationId)
+    await this.withFileLock(file, async () => {
+      if (!await this.pathExists(file)) {
+        logger.debug(`Transcript file does not exist: ${this.protocol(file)}`)
+        return
+      }
+      await fs.unlink(file)
+    })
+  }
+
+  /**
+   * Loads a transcript from a file.
+   */
+  private async loadTranscriptAsync (transcriptFile: string): Promise<Activity[]> {
+    if (!await this.pathExists(transcriptFile)) {
+      return []
+    }
+
+    const json = await fs.readFile(transcriptFile, 'utf-8')
+    const result = JSON.parse(json)
+    return result.map(Activity.fromObject)
+  }
+
+  /**
+   * Executes a file operation with exclusive locking per file.
+   * This ensures that concurrent writes to the same transcript file are serialized.
+   */
+  private async withFileLock<T> (transcriptFile: string, operation: () => Promise<T>): Promise<T> {
+    // Get the current lock chain for this file
+    const existingLock = this._fileLocks.get(transcriptFile) ?? Promise.resolve()
+
+    // Create a new lock that waits for the existing one and then performs the operation
+    const newLock = existingLock.then(async () => {
+      return await operation()
+    }).catch(error => {
+      logger.warn('Error in write chain:', error)
+      throw error
+    })
+
+    // Update the lock chain
+    this._fileLocks.set(transcriptFile, newLock)
+
+    // Wait for this operation to complete
+    try {
+      return await newLock
+    } finally {
+      // Clean up if this was the last operation in the chain
+      if (this._fileLocks.get(transcriptFile) === newLock) {
+        this._fileLocks.delete(transcriptFile)
+      }
+    }
+  }
+
+  /**
+   * Performs the actual write operation to the transcript file.
+   */
+  private async logActivityToFile (activity: Activity, transcriptFile: string): Promise<void> {
+    const activityStr = JSON.stringify(activity)
+
+    if (!await this.pathExists(transcriptFile)) {
+      const folder = path.dirname(transcriptFile)
+      if (!await this.pathExists(folder)) {
+        await fs.mkdir(folder, { recursive: true })
+      }
+      await fs.writeFile(transcriptFile, `[${activityStr}]`, 'utf-8')
+      return
+    }
+
+    // Use file handle to append efficiently
+    const fileHandle = await fs.open(transcriptFile, 'r+')
+    try {
+      const stats = await fileHandle.stat()
+
+      // Seek to before the closing bracket
+      const position = Math.max(0, stats.size - 1)
+
+      // Write the comma, new activity, and closing bracket
+      const appendContent = `,${EOL}${activityStr}]`
+      await fileHandle.write(appendContent, position)
+      // Truncate any remaining content (in case the file had trailing data)
+      await fileHandle.truncate(position + Buffer.byteLength(appendContent))
+    } finally {
+      await fileHandle.close()
+    }
+  }
+
+  /**
+   * Updates a message in the transcript.
+   */
+  private async messageUpdateAsync (activity: Activity, transcriptFile: string): Promise<void> {
+    // Load all activities
+    const transcript = await this.loadTranscriptAsync(transcriptFile)
+
+    for (let i = 0; i < transcript.length; i++) {
+      const originalActivity = transcript[i]
+      if (originalActivity.id === activity.id) {
+        // Clone and update the activity
+        const updatedActivity: Activity = { ...activity } as Activity
+        updatedActivity.type = originalActivity.type // Fixup original type (should be Message)
+        updatedActivity.localTimestamp = originalActivity.localTimestamp
+        updatedActivity.timestamp = originalActivity.timestamp
+        transcript[i] = updatedActivity
+
+        const json = JSON.stringify(transcript)
+        await fs.writeFile(transcriptFile, json, 'utf-8')
+        return
+      }
+    }
+  }
+
+  /**
+   * Deletes a message from the transcript (tombstones it).
+   */
+  private async messageDeleteAsync (activity: Activity, transcriptFile: string): Promise<void> {
+    // Load all activities
+    const transcript = await this.loadTranscriptAsync(transcriptFile)
+
+    // If message delete comes in, tombstone the message in the transcript
+    for (let index = 0; index < transcript.length; index++) {
+      const originalActivity = transcript[index]
+      if (originalActivity.id === activity.id) {
+        // Tombstone the original message
+        transcript[index] = {
+          type: ActivityTypes.MessageDelete,
+          id: originalActivity.id,
+          from: {
+            id: 'deleted',
+            role: originalActivity.from?.role
+          },
+          recipient: {
+            id: 'deleted',
+            role: originalActivity.recipient?.role
+          },
+          locale: originalActivity.locale,
+          localTimestamp: originalActivity.timestamp,
+          timestamp: originalActivity.timestamp,
+          channelId: originalActivity.channelId,
+          conversation: originalActivity.conversation,
+          serviceUrl: originalActivity.serviceUrl,
+          replyToId: originalActivity.replyToId
+        } as Activity
+
+        const json = JSON.stringify(transcript)
+        await fs.writeFile(transcriptFile, json, 'utf-8')
+        return
+      }
+    }
+  }
+
+  /**
+   * Sanitizes a string by removing invalid characters.
+   */
+  private static sanitizeString (str: string, invalidChars: string[]): string {
+    if (!str?.trim()) {
+      return str
+    }
+
+    // Preemptively check for : in string and replace with _
+    let result = str.replaceAll(':', '_')
+
+    // Remove invalid characters
+    for (const invalidChar of invalidChars) {
+      result = result.replaceAll(invalidChar, '')
+    }
+
+    return result
+  }
+
+  /**
+   * Gets the transcript file path for a conversation.
+   */
+  private getTranscriptFile (channelId: string, conversationId: string): string {
+    if (!channelId?.trim()) {
+      throw new Error('channelId is required.')
+    }
+
+    if (!conversationId?.trim()) {
+      throw new Error('conversationId is required.')
+    }
+
+    // Get invalid filename characters (cross-platform)
+    const invalidChars = this.getInvalidFileNameChars()
+    let fileName = FileTranscriptLogger.sanitizeString(conversationId, invalidChars)
+
+    const maxLength = FileTranscriptLogger.MAX_FILE_NAME_SIZE - FileTranscriptLogger.TRANSCRIPT_FILE_EXTENSION.length
+    if (fileName && fileName.length > maxLength) {
+      fileName = fileName.substring(0, maxLength)
+    }
+
+    const channelFolder = this.getChannelFolder(channelId)
+    return path.join(channelFolder, fileName + FileTranscriptLogger.TRANSCRIPT_FILE_EXTENSION)
+  }
+
+  /**
+   * Gets the channel folder path, creating it if necessary.
+   */
+  private getChannelFolder (channelId: string): string {
+    if (!channelId?.trim()) {
+      throw new Error('channelId is required.')
+    }
+
+    const invalidChars = this.getInvalidPathChars()
+    const folderName = FileTranscriptLogger.sanitizeString(channelId, invalidChars)
+    return path.join(this._folder, folderName)
+  }
+
+  /**
+   * Checks if a file or directory exists.
+   */
+  private async pathExists (path: string): Promise<boolean> {
+    try {
+      await fs.stat(path)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Gets invalid filename characters for the current platform.
+   */
+  private getInvalidFileNameChars (): string[] {
+    // Windows invalid filename chars: < > : " / \ | ? *
+    // Unix systems are more permissive, but / is always invalid
+    const invalid = this.getInvalidPathChars()
+    if (process.platform === 'win32') {
+      return [...invalid, '/', '\\']
+    } else {
+      return [...invalid, '/']
+    }
+  }
+
+  /**
+   * Gets invalid path characters for the current platform.
+   */
+  private getInvalidPathChars (): string[] {
+    // Similar to filename chars but allows directory separators in the middle
+    if (process.platform === 'win32') {
+      return ['<', '>', ':', '"', '|', '?', '*', '\0']
+    } else {
+    // Unix/Linux: only null byte is invalid in paths
+      return ['\0']
+    }
+  }
+
+  /**
+   * Adds file:// protocol to a file path.
+   */
+  private protocol (filePath: string): string {
+    return `file://${filePath.replace(/\\/g, '/')}`
+  }
+}