@microsoft/agents-hosting 1.1.0-alpha.5 → 1.1.0-alpha.58

package/src/app/auth/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity } from '@microsoft/agents-activity'
+import { Storage, StoreItem } from '../../storage'
+import { TurnContext } from '../../turnContext'
+import { AgenticAuthorizationOptions, AzureBotAuthorizationOptions } from './handlers'
+import { TokenResponse } from '../../oauth'
+import { Connections } from '../../auth/connections'
+
+/**
+ * Authorization configuration options.
+ */
+export type AuthorizationOptions = Record<string, AzureBotAuthorizationOptions | AgenticAuthorizationOptions>
+
+/**
+ * Represents the status of a handler registration attempt.
+ */
+export enum AuthorizationHandlerStatus {
+  /** The handler has approved the request - validation passed */
+  APPROVED = 'approved',
+  /** The handler registration is pending further action */
+  PENDING = 'pending',
+  /** The handler has rejected the request - validation failed */
+  REJECTED = 'rejected',
+  /** The handler has ignored the request - no action taken */
+  IGNORED = 'ignored',
+  /** The handler requires revalidation */
+  REVALIDATE = 'revalidate'
+}
+
+/**
+ * Active handler manager information.
+ */
+export interface ActiveAuthorizationHandler extends StoreItem {
+  /**
+   * Unique identifier for the handler.
+   */
+  readonly id: string
+  /**
+   * The current activity associated with the handler.
+   */
+  activity: Activity
+}
+
+export interface AuthorizationHandler {
+  /**
+   * Unique identifier for the handler.
+   */
+  readonly id: string
+  /**
+   * Initiates the sign-in process for the handler.
+   * @param context The turn context.
+   * @param active Optional active handler data.
+   * @returns The status of the sign-in attempt.
+   */
+  signin(context: TurnContext, active?: ActiveAuthorizationHandler): Promise<AuthorizationHandlerStatus>
+  /**
+   * Initiates the sign-out process for the handler.
+   * @param context The turn context.
+   * @returns A promise that resolves to a boolean indicating the success of the sign-out attempt.
+   */
+  signout(context: TurnContext): Promise<boolean>;
+  /**
+   * Retrieves an access token for the specified scopes.
+   * @param context The turn context.
+   * @param options Optional token request options.
+   * @returns The access token response.
+   */
+  token(context: TurnContext, options?: AuthorizationHandlerTokenOptions): Promise<TokenResponse>;
+  /**
+   * Registers a callback to be invoked when the sign-in process is successful.
+   * @param callback The callback to invoke on success.
+   */
+  onSuccess(callback: (context: TurnContext) => Promise<void> | void): void;
+  /**
+   * Registers a callback to be invoked when the sign-in process fails.
+   * @param callback The callback to invoke on failure.
+   */
+  onFailure(callback: (context: TurnContext, reason?: string) => Promise<void> | void): void;
+}
+
+/**
+ * Common settings required by authorization handlers.
+ */
+export interface AuthorizationHandlerSettings {
+  /**
+   * Storage instance for persisting handler state.
+   */
+  storage: Storage
+  /**
+   * Connections instance for managing authentication connections.
+   */
+  connections: Connections
+}
+
+/**
+ * Options for token requests in authorization handlers.
+ */
+export interface AuthorizationHandlerTokenOptions {
+  /**
+   * Optional name of the connection to use for the token request. Usually used for OBO flows.
+   */
+  connection?: string
+  /**
+   * Optional scopes to request in the token. Usually used for OBO flows.
+   */
+  scopes?: string[]
+}

package/src/app/index.ts

@@ -2,13 +2,12 @@ export * from './agentApplication'
 export * from './agentApplicationBuilder'
 export * from './agentApplicationOptions'
 export * from './appRoute'
-export * from './attachmentDownloader'
-export * from './authorization'
-export * from './conversationUpdateEvents'
 export * from './routeHandler'
 export * from './routeList'
 export * from './routeRank'
 export * from './routeSelector'
+export * from './attachmentDownloader'
+export * from './conversationUpdateEvents'
 export * from './turnState'
 export * from './turnEvents'
 export * from './turnStateEntry'

package/src/app/routeList.ts

@@ -17,17 +17,36 @@ export class RouteList<TState extends TurnState> {
     handler: RouteHandler<TState>,
     isInvokeRoute: boolean = false,
     rank: number = RouteRank.Unspecified,
-    authHandlers: string[] = []
+    authHandlers: string[] = [],
+    isAgenticRoute: boolean = false
   ): this {
-    this._routes.push({ selector, handler, isInvokeRoute, rank, authHandlers })
+    this._routes.push({ selector, handler, isInvokeRoute, rank, authHandlers, isAgenticRoute })
 
-    // Invoke selectors are first, then order by rank ascending
+    // Ordered by:
+    //    Agentic + Invoke
+    //    Invoke
+    //    Agentic
+    //    Other
+    // Then by Rank
     this._routes.sort((a, b) => {
-      if (a.isInvokeRoute !== b.isInvokeRoute) {
-        return a.isInvokeRoute ? -1 : 1
+      const getPriority = (route: AppRoute<TState>) => {
+        if (route.isAgenticRoute && route.isInvokeRoute) return 0
+        if (route.isInvokeRoute) return 1
+        if (route.isAgenticRoute) return 2
+        return 3
       }
+
+      const priorityA = getPriority(a)
+      const priorityB = getPriority(b)
+
+      if (priorityA !== priorityB) {
+        return priorityA - priorityB
+      }
+
+      // If priorities are equal, sort by rank
       return (a.rank ?? 0) - (b.rank ?? 0)
     })
+
     return this
   }
 

package/src/app/streaming/streamingResponse.ts

@@ -191,7 +191,8 @@ export class StreamingResponse {
           appearance: {
             '@type': 'DigitalDocument',
             name: citation.title || `Document #${currPos + 1}`,
-            abstract: CitationUtil.snippet(citation.content, 477)
+            abstract: CitationUtil.snippet(citation.content, 477),
+            url: citation.url!
           }
         }
         currPos++

package/src/auth/MemoryCache.ts

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+const CACHE_PURGE_INTERVAL = 60000 // 60 seconds
+
+/**
+ * Simple in-memory cache with TTL support.
+ * This is used to store authentication tokens for Agentic Identity scenarios only!
+ */
+export class MemoryCache<T> {
+  private cache = new Map<string, { value: T; validUntil: number }>()
+  private purgeInterval?: NodeJS.Timeout
+
+  /**
+   * Clears the purge interval to allow the process to exit cleanly
+   */
+  destroy (): void {
+    if (this.purgeInterval) {
+      clearInterval(this.purgeInterval)
+      this.purgeInterval = undefined
+    }
+  }
+
+  set (key: string, value: T, ttlSeconds: number): void {
+    const validUntil = Date.now() + (ttlSeconds * 1000)
+    this.cache.set(key, { value, validUntil })
+    if (!this.purgeInterval) {
+      this.purgeInterval = setInterval(() => this.purge(), CACHE_PURGE_INTERVAL)
+    }
+  }
+
+  get (key: string): T | undefined {
+    const item = this.cache.get(key)
+    if (!item) {
+      return undefined
+    }
+
+    // Check if item has expired
+    if (Date.now() > item.validUntil) {
+      this.cache.delete(key)
+      return undefined
+    }
+    return item.value
+  }
+
+  delete (key: string): boolean {
+    return this.cache.delete(key)
+  }
+
+  purge (): void {
+    const now = Date.now()
+    for (const [key, { validUntil }] of this.cache.entries()) {
+      if (now > validUntil) {
+        this.cache.delete(key)
+      }
+    }
+  }
+}

package/src/auth/authConfiguration.ts

@@ -3,6 +3,13 @@
  * Licensed under the MIT License.
  */
 
+import { debug } from '@microsoft/agents-activity/logger'
+import { ConnectionMapItem } from './msalConnectionManager'
+import objectPath from 'object-path'
+
+const logger = debug('agents:authConfiguration')
+const DEFAULT_CONNECTION = 'serviceConnection'
+
 /**
  * Represents the authentication configuration.
  */
@@ -15,7 +22,7 @@ export interface AuthConfiguration {
   /**
    * The client ID for the authentication configuration. Required in production.
    */
-  clientId: string
+  clientId?: string
 
   /**
    * The client secret for the authentication configuration.
@@ -35,7 +42,7 @@ export interface AuthConfiguration {
   /**
    * A list of valid issuers for the authentication configuration.
    */
-  issuers: string[]
+  issuers?: string[]
 
   /**
    * The connection name for the authentication configuration.
@@ -56,6 +63,28 @@ export interface AuthConfiguration {
    * see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
    */
   authority?: string
+
+  scope?: string
+
+  /**
+   * A map of connection names to their respective authentication configurations.
+   */
+  connections?: Map<string, AuthConfiguration>
+
+  /**
+   * A list of connection map items to map service URLs to connection names.
+   */
+  connectionsMap?: ConnectionMapItem[],
+
+  /**
+   * An optional alternative blueprint Connection name used when constructing a connector client.
+   */
+  altBlueprintConnectionName?: string
+
+  /**
+   * The path to K8s provided token.
+   */
+  WIDAssertionFile?: string
 }
 
 /**
@@ -83,44 +112,43 @@ export interface AuthConfiguration {
  * ```
  *
  */
-export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (cnxName?: string) => {
-  if (cnxName === undefined) {
-    const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
-    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,
-      authority,
-      issuers: [
-        'https://api.botframework.com',
-        `https://sts.windows.net/${process.env.tenantId}/`,
-        `${authority}/${process.env.tenantId}/v2.0`
-      ],
-    }
+export const loadAuthConfigFromEnv = (cnxName?: string): AuthConfiguration => {
+  const envConnections = loadConnectionsMapFromEnv()
+  let authConfig: AuthConfiguration
+
+  if (envConnections.connectionsMap.length === 0) {
+    // No connections provided, we need to populate the connections map with the old config settings
+    authConfig = buildLegacyAuthConfig(cnxName)
+    envConnections.connections.set(DEFAULT_CONNECTION, authConfig)
+    envConnections.connectionsMap.push({
+      serviceUrl: '*',
+      connection: DEFAULT_CONNECTION,
+    })
   } else {
-    const authority = process.env[`${cnxName}_authorityEndpoint`] ?? 'https://login.microsoftonline.com'
-    return {
-      tenantId: process.env[`${cnxName}_tenantId`],
-      clientId: process.env[`${cnxName}_clientId`] ?? (() => { throw new Error(`ClientId not found for connection: ${cnxName}`) })(),
-      clientSecret: process.env[`${cnxName}_clientSecret`],
-      certPemFile: process.env[`${cnxName}_certPemFile`],
-      certKeyFile: process.env[`${cnxName}_certKeyFile`],
-      connectionName: process.env[`${cnxName}_connectionName`],
-      FICClientId: process.env[`${cnxName}_FICClientId`],
-      authority,
-      issuers: [
-        'https://api.botframework.com',
-        `https://sts.windows.net/${process.env[`${cnxName}_tenantId`]}/`,
-        `${authority}/${process.env[`${cnxName}_tenantId`]}/v2.0`
-      ]
+    // There are connections provided, use the default or specified connection
+    if (cnxName) {
+      const entry = envConnections.connections.get(cnxName)
+      if (entry) {
+        authConfig = entry
+      } else {
+        throw new Error(`Connection "${cnxName}" not found in environment.`)
+      }
+    } else {
+      const defaultItem = envConnections.connectionsMap.find((item) => item.serviceUrl === '*')
+      const defaultConn = defaultItem ? envConnections.connections.get(defaultItem.connection) : undefined
+      if (!defaultConn) {
+        throw new Error('No default connection found in environment connections.')
+      }
+      authConfig = defaultConn
     }
+
+    authConfig.authority ??= 'https://login.microsoftonline.com'
+    authConfig.issuers ??= getDefaultIssuers(authConfig.tenantId ?? '', authConfig.authority)
+  }
+
+  return {
+    ...authConfig,
+    ...envConnections,
   }
 }
 
@@ -139,23 +167,201 @@ export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (c
  *
  */
 export const loadPrevAuthConfigFromEnv: () => AuthConfiguration = () => {
-  if (process.env.MicrosoftAppId === undefined && process.env.NODE_ENV === 'production') {
+  const envConnections = loadConnectionsMapFromEnv()
+  let authConfig: AuthConfiguration = {}
+
+  if (envConnections.connectionsMap.length === 0) {
+    // No connections provided, we need to populate the connection map with the old config settings
+    if (process.env.MicrosoftAppId === undefined && process.env.NODE_ENV === 'production') {
+      throw new Error('ClientId required in production')
+    }
+    const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
+    authConfig = {
+      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,
+      authority,
+      scope: process.env.scope,
+      issuers: getDefaultIssuers(process.env.MicrosoftAppTenantId ?? '', authority),
+      altBlueprintConnectionName: process.env.altBlueprintConnectionName,
+      WIDAssertionFile: process.env.WIDAssertionFile,
+    }
+    envConnections.connections.set(DEFAULT_CONNECTION, authConfig)
+    envConnections.connectionsMap.push({
+      serviceUrl: '*',
+      connection: DEFAULT_CONNECTION,
+    })
+  } else {
+    // There are connections provided, use the default one.
+    const defaultItem = envConnections.connectionsMap.find((item) => item.serviceUrl === '*')
+    const defaultConn = defaultItem ? envConnections.connections.get(defaultItem.connection) : undefined
+    if (!defaultConn) {
+      throw new Error('No default connection found in environment connections.')
+    }
+    authConfig = defaultConn
+  }
+
+  authConfig.authority ??= 'https://login.microsoftonline.com'
+  authConfig.issuers ??= getDefaultIssuers(authConfig.tenantId ?? '', authConfig.authority)
+
+  return { ...authConfig, ...envConnections }
+}
+
+function loadConnectionsMapFromEnv () {
+  const envVars = process.env
+  const connections = new Map<string, AuthConfiguration>()
+  const connectionsMap: ConnectionMapItem[] = []
+
+  for (const [key, value] of Object.entries(envVars)) {
+    if (key.startsWith('connections__')) {
+      const parts = key.split('__')
+      if (parts.length >= 4 && parts[2] === 'settings') {
+        const connectionName = parts[1]
+        const propertyPath = parts.slice(3).join('.') // e.g., 'issuers.0' or 'clientId'
+
+        let config = connections.get(connectionName)
+        if (!config) {
+          config = {}
+          connections.set(connectionName, config)
+        }
+
+        objectPath.set(config, propertyPath, value)
+      }
+    } else if (key.startsWith('connectionsMap__')) {
+      const parts = key.split('__')
+      if (parts.length === 3) {
+        const index = parseInt(parts[1], 10)
+        const property = parts[2]
+
+        if (!connectionsMap[index]) {
+          connectionsMap[index] = { serviceUrl: '', connection: '' }
+        }
+
+        (connectionsMap[index] as any)[property] = value
+      }
+    }
+  }
+
+  if (connections.size === 0) {
+    logger.warn('No connections found in configuration.')
+  }
+
+  if (connectionsMap.length === 0) {
+    logger.warn('No connections map found in configuration.')
+    if (connections.size > 0) {
+      const firstEntry = connections.entries().next().value
+
+      if (firstEntry) {
+        const [firstKey] = firstEntry
+        // Provide a default connection map if none is specified
+        connectionsMap.push({
+          serviceUrl: '*',
+          connection: firstKey,
+        })
+      }
+    }
+  }
+
+  return {
+    connections,
+    connectionsMap,
+  }
+}
+
+/**
+ * Loads the authentication configuration from the provided config or from the environment variables
+ * providing default values for authority and issuers.
+ *
+ * @returns The authentication configuration.
+ * @throws Will throw an error if clientId is not provided in production.
+ *
+ * @example
+ * ```
+ * tenantId=your-tenant-id
+ * clientId=your-client-id
+ * clientSecret=your-client-secret
+ *
+ * certPemFile=your-cert-pem-file
+ * certKeyFile=your-cert-key-file
+ *
+ * FICClientId=your-FIC-client-id
+ *
+ * connectionName=your-connection-name
+ * authority=your-authority-endpoint
+ * ```
+ *
+ */
+export function getAuthConfigWithDefaults (config?: AuthConfiguration): AuthConfiguration {
+  if (!config) return loadAuthConfigFromEnv()
+
+  const providedConnections = config.connections && config.connectionsMap
+    ? { connections: config.connections, connectionsMap: config.connectionsMap }
+    : undefined
+
+  const connections = providedConnections ?? loadConnectionsMapFromEnv()
+
+  let mergedConfig: AuthConfiguration
+
+  if (connections && connections.connectionsMap?.length === 0) {
+    // No connections provided, we need to populate the connections map with the old config settings
+    mergedConfig = buildLegacyAuthConfig(undefined, config)
+    connections.connections?.set(DEFAULT_CONNECTION, mergedConfig)
+    connections.connectionsMap.push({ serviceUrl: '*', connection: DEFAULT_CONNECTION })
+  } else {
+    // There are connections provided, use the default connection
+    const defaultItem = connections.connectionsMap?.find((item) => item.serviceUrl === '*')
+    const defaultConn = defaultItem ? connections.connections?.get(defaultItem.connection) : undefined
+    if (!defaultConn) {
+      throw new Error('No default connection found in environment connections.')
+    }
+    mergedConfig = buildLegacyAuthConfig(undefined, defaultConn)
+  }
+
+  return {
+    ...mergedConfig,
+    ...connections,
+  }
+}
+
+function buildLegacyAuthConfig (envPrefix: string = '', customConfig?: AuthConfiguration): AuthConfiguration {
+  const prefix = envPrefix ? `${envPrefix}_` : ''
+  const authority = customConfig?.authority ?? process.env[`${prefix}authorityEndpoint`] ?? 'https://login.microsoftonline.com'
+
+  const clientId = customConfig?.clientId ?? process.env[`${prefix}clientId`]
+
+  if (!clientId && !envPrefix && process.env.NODE_ENV === 'production') {
     throw new Error('ClientId required in production')
   }
-  const authority = process.env.authorityEndpoint ?? 'https://login.microsoftonline.com'
+  if (!clientId && envPrefix) {
+    throw new Error(`ClientId not found for connection: ${envPrefix}`)
+  }
+
+  const tenantId = customConfig?.tenantId ?? process.env[`${prefix}tenantId`]
+
   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,
+    tenantId,
+    clientId: clientId!,
+    clientSecret: customConfig?.clientSecret ?? process.env[`${prefix}clientSecret`],
+    certPemFile: customConfig?.certPemFile ?? process.env[`${prefix}certPemFile`],
+    certKeyFile: customConfig?.certKeyFile ?? process.env[`${prefix}certKeyFile`],
+    connectionName: customConfig?.connectionName ?? process.env[`${prefix}connectionName`],
+    FICClientId: customConfig?.FICClientId ?? process.env[`${prefix}FICClientId`],
     authority,
-    issuers: [
-      'https://api.botframework.com',
-      `https://sts.windows.net/${process.env.MicrosoftAppTenantId}/`,
-      `${authority}/${process.env.MicrosoftAppTenantId}/v2.0`
-    ]
+    scope: customConfig?.scope ?? process.env[`${prefix}scope`],
+    issuers: customConfig?.issuers ?? getDefaultIssuers(tenantId as string, authority),
+    altBlueprintConnectionName: customConfig?.altBlueprintConnectionName ?? process.env[`${prefix}altBlueprintConnectionName`],
+    WIDAssertionFile: customConfig?.WIDAssertionFile ?? process.env[`${prefix}WIDAssertionFile`]
   }
 }
+
+function getDefaultIssuers (tenantId: string, authority: string) : string[] {
+  return [
+    'https://api.botframework.com',
+    `https://sts.windows.net/${tenantId}/`,
+    `${authority}/${tenantId}/v2.0`
+  ]
+}

package/src/auth/authConstants.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export const ApxLocalScope = 'c16e153d-5d2b-4c21-b7f4-b05ee5d516f1/.default'
+export const ApxDevScope = '0d94caae-b412-4943-8a68-83135ad6d35f/.default'
+export const ApxProductionScope = '5a807f24-c9de-44ee-a3a7-329e88a00ffc/.default'
+export const ApxGCCScope = 'c9475445-9789-4fef-9ec5-cde4a9bcd446/.default'
+export const ApxGCCHScope = '6f669b9e-7701-4e2b-b624-82c9207fde26/.default'
+export const ApxDoDScope = '0a069c81-8c7c-4712-886b-9c542d673ffb/.default'
+export const ApxGallatinScope = 'bd004c8e-5acf-4c48-8570-4e7d46b2f63b/.default'

package/src/auth/authProvider.ts

@@ -16,4 +16,35 @@ export interface AuthProvider {
    * @returns A promise that resolves to the access token.
    */
   getAccessToken: (authConfig: AuthConfiguration, scope: string) => Promise<string>
+
+  /**
+   * Get an access token for the agentic application
+   * @param agentAppInstanceId
+   * @returns a promise that resolves to the access token.
+   */
+  getAgenticApplicationToken: (agentAppInstanceId: string) => Promise<string>
+
+  /**
+   * Get an access token for the agentic instance
+   * @param agentAppInstanceId
+   * @returns a promise that resolves to the access token.
+   */
+  getAgenticInstanceToken: (agentAppInstanceId: string) => Promise<string>
+
+  /**
+   * Get an access token for the agentic user
+   * @param agentAppInstanceId
+   * @param upn
+   * @param scopes
+   * @returns a promise that resolves to the access token.
+   */
+  getAgenticUserToken: (agentAppInstanceId: string, upn: string, scopes: string[]) => Promise<string>
+
+  acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+  acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
+  acquireTokenOnBehalfOf (
+    authConfigOrScopes: AuthConfiguration | string[],
+    scopesOrOboAssertion?: string[] | string,
+    oboAssertion?: string
+  ): Promise<string>
 }