@microsoft/agents-hosting 1.5.0-beta.6.ga236d9a19c → 1.5.1

package/src/app/auth/types.ts

@@ -13,7 +13,7 @@ import { Connections } from '../../auth/connections'
 /**
  * Authorization configuration options.
  */
-export type AuthorizationOptions = Record<string, AzureBotAuthorizationOptions | AgenticAuthorizationOptions>
+export type AuthorizationOptions = Record<string, (AzureBotAuthorizationOptions & AzureBotAuthorizationOptionsLegacy) | AgenticAuthorizationOptions>
 
 /**
  * Represents the status of a handler registration attempt.
@@ -50,6 +50,14 @@ export interface AuthorizationHandler {
    * Unique identifier for the handler.
    */
   readonly id: string
+  /**
+   * The type of this handler (resolved, including env vars).
+   */
+  readonly type?: string
+  /**
+   * The scopes configured for this handler (resolved, including env vars).
+   */
+  readonly scopes?: string[]
   /**
    * Initiates the sign-in process for the handler.
    * @param context The turn context.
@@ -109,3 +117,96 @@ export interface AuthorizationHandlerTokenOptions {
    */
   scopes?: string[]
 }
+
+/**
+ * Interface defining an authorization handler configuration.
+ * @remarks
+ * Properties can be configured via environment variables (case-insensitive).
+ * Use the format: `AgentApplication__UserAuthorization__handlers__{handlerId}__settings__{propertyName}`
+ * where `{handlerId}` is the handler's unique identifier and `{propertyName}` matches the property name.
+ *
+ * @example
+ * ```env
+ * # For a handler with id "myAuth":
+ * AgentApplication__UserAuthorization__handlers__myAuth__settings__azureBotOAuthConnectionName=MyConnection
+ * AgentApplication__UserAuthorization__handlers__myAuth__settings__oboScopes=api://scope1 api://scope2
+ * ```
+ */
+export interface AzureBotAuthorizationOptionsLegacy {
+  /**
+   * Connection name for the auth provider.
+   * @deprecated Use `azureBotOAuthConnectionName` instead.
+   * @remarks Env (legacy): `{handlerId}_connectionName`
+   */
+  name?: string,
+  /**
+   * Maximum number of attempts for entering the magic code. Defaults to 2.
+   * @deprecated Use `invalidSignInRetryMax` instead.
+   * @remarks Env (legacy): `{handlerId}_maxAttempts`
+   */
+  maxAttempts?: number
+  /**
+   * Messages to display for various authentication scenarios.
+   * @deprecated Use `invalidSignInRetryMessage`, `invalidSignInRetryMessageFormat`, and `invalidSignInRetryMaxExceededMessage` instead.
+   * @remarks
+   * Env (legacy):
+   * - `{handlerId}_messages_invalidCode`
+   * - `{handlerId}_messages_invalidCodeFormat`
+   * - `{handlerId}_messages_maxAttemptsExceeded`
+   */
+  messages?: AzureBotAuthorizationOptionsMessages
+  /**
+   * Settings for on-behalf-of token acquisition.
+   * @deprecated Use `oboConnectionName` and `oboScopes` instead.
+   * @remarks
+   * Env (legacy):
+   * - `{handlerId}_obo_connection`
+   * - `{handlerId}_obo_scopes` (comma or space-separated)
+   */
+  obo?: AzureBotAuthorizationOptionsOBO
+}
+
+/**
+ * @deprecated
+ * Messages configuration for the AzureBotAuthorization handler.
+ */
+interface AzureBotAuthorizationOptionsMessages {
+  /**
+   * @deprecated Use `invalidSignInRetryMessage` instead.
+   * Message displayed when an invalid code is entered.
+   * Use `{code}` as a placeholder for the entered code.
+   * Defaults to: 'The code entered is invalid. Please sign-in again to continue.'
+   */
+  invalidCode?: string
+  /**
+   * @deprecated Use `invalidSignInRetryMessageFormat` instead.
+   * Message displayed when the entered code format is invalid.
+   * Use `{attemptsLeft}` as a placeholder for the number of attempts left.
+   * Defaults to: 'Please enter a valid **6-digit** code format (_e.g. 123456_).\r\n**{attemptsLeft} attempt(s) left...**'
+   */
+  invalidCodeFormat?: string
+  /**
+   * @deprecated Use `invalidSignInRetryMaxExceededMessage` instead.
+   * Message displayed when the maximum number of attempts is exceeded.
+   * Use `{maxAttempts}` as a placeholder for the maximum number of attempts.
+   * Defaults to: 'You have exceeded the maximum number of sign-in attempts ({maxAttempts}).'
+   */
+  maxAttemptsExceeded?: string
+}
+
+/**
+ * @deprecated
+ * Settings for on-behalf-of token acquisition.
+ */
+interface AzureBotAuthorizationOptionsOBO {
+  /**
+   * @deprecated Use `oboConnectionName` instead.
+   * Connection name to use for on-behalf-of token acquisition.
+   */
+  connection?: string
+  /**
+   * @deprecated Use `oboScopes` instead.
+   * Scopes to request for on-behalf-of token acquisition.
+   */
+  scopes?: string[]
+}

package/src/app/auth/utils.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TurnContext } from '../../turnContext'
+import { InvokeResponse } from '../../invoke'
+import { Activity, ActivityTypes, Channels } from '@microsoft/agents-activity'
+
+/**
+ * Sends an InvokeResponse activity if the channel is Microsoft Teams, including Copilot within MS Teams.
+ */
+export function sendInvokeResponse<T> (context: TurnContext, response: InvokeResponse<T>) {
+  if (context.activity.channelIdChannel !== Channels.Msteams) {
+    return Promise.resolve()
+  }
+
+  return context.sendActivity(Activity.fromObject({
+    type: ActivityTypes.InvokeResponse,
+    value: response
+  }))
+}

package/src/app/index.ts

@@ -19,3 +19,4 @@ export * from './adaptiveCards'
 export * from './streaming/streamingResponse'
 export * from './streaming/citation'
 export * from './teamsAttachmentDownloader'
+export * from './proactive'

package/src/app/proactive/conversation.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { JwtPayload } from 'jsonwebtoken'
+import type { ConversationReference } from '@microsoft/agents-activity'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import type { TurnContext } from '../../turnContext'
+import { Errors } from '../../errorHelper'
+
+/**
+ * JWT-like claims identifying the agent for proactive authentication.
+ * `aud` (the agent's client ID) is required; all other fields are optional.
+ */
+export interface ConversationClaims {
+  aud: string
+  azp?: string
+  appid?: string
+  tid?: string
+  [key: string]: string | undefined
+}
+
+/**
+ * A serializable pair of a `ConversationReference` and the JWT claims needed
+ * to authenticate proactive calls on behalf of this agent.
+ *
+ * Instances are stored in and retrieved from the proactive storage backend.
+ * The `identity` getter produces the `JwtPayload` shape expected by
+ * `adapter.continueConversation()`.
+ */
+export class Conversation {
+  reference: ConversationReference
+  claims: ConversationClaims
+
+  constructor (context: TurnContext)
+  constructor (claims: ConversationClaims, reference: ConversationReference)
+  constructor (
+    contextOrClaims: TurnContext | ConversationClaims,
+    reference?: ConversationReference
+  ) {
+    if ('activity' in contextOrClaims) {
+      // TurnContext overload
+      const context = contextOrClaims as TurnContext
+      this.reference = context.activity.getConversationReference()
+      const id = context.identity as JwtPayload | undefined
+      this.claims = {
+        ...(id ?? {}),
+        aud: Array.isArray(id?.aud) ? (id.aud as string[])[0] : (id?.aud ?? '')
+      } as ConversationClaims
+    } else {
+      // (claims, reference) overload — matches C# parameter order
+      this.claims = contextOrClaims as ConversationClaims
+      this.reference = reference!
+    }
+  }
+
+  /**
+   * Returns a `JwtPayload`-compatible object for passing to
+   * `adapter.continueConversation()` as `botAppIdOrIdentity`.
+   */
+  get identity (): JwtPayload {
+    return this.claims as unknown as JwtPayload
+  }
+
+  /**
+   * Returns a JSON string of `{ reference, claims }` — suitable for use in
+   * HTTP request bodies when passing a conversation to another service.
+   */
+  toJson (): string {
+    return JSON.stringify({ reference: this.reference, claims: this.claims })
+  }
+
+  /**
+   * Throws if any required field is missing.
+   * Called by `Proactive.storeConversation()` before writing to storage.
+   */
+  validate (): void {
+    if (!this.reference.conversation?.id) {
+      throw ExceptionHelper.generateException(Error, Errors.ConversationInvalidId)
+    }
+    if (!this.reference.serviceUrl) {
+      throw ExceptionHelper.generateException(Error, Errors.ConversationInvalidServiceUrl)
+    }
+    if (!this.claims.aud) {
+      throw ExceptionHelper.generateException(Error, Errors.ConversationInvalidAud)
+    }
+  }
+}

package/src/app/proactive/conversationBuilder.ts

@@ -0,0 +1,139 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { ChannelAccount, ConversationAccount, ConversationReference } from '@microsoft/agents-activity'
+import type { TurnContext } from '../../turnContext'
+import { Conversation, type ConversationClaims } from './conversation'
+import { ConversationReferenceBuilder } from './conversationReferenceBuilder'
+
+/**
+ * Fluent builder for the `Conversation` class.
+ *
+ * @example
+ * ```typescript
+ * // Build from scratch
+ * const conv = ConversationBuilder
+ *   .create('my-client-id', 'msteams')
+ *   .withUser('user-aad-id')
+ *   .withConversationId('19:channel@thread.skype')
+ *   .build()
+ *
+ * // Build from a live TurnContext
+ * const conv = ConversationBuilder.fromContext(turnContext).build()
+ * ```
+ */
+export class ConversationBuilder {
+  private readonly _agentClientId: string
+  private readonly _channelId: string
+  private readonly _serviceUrl: string
+  private _claims: ConversationClaims
+  private _reference: Partial<ConversationReference>
+
+  private constructor (
+    agentClientId: string,
+    channelId: string,
+    serviceUrl: string,
+    claims: ConversationClaims,
+    reference: Partial<ConversationReference>
+  ) {
+    this._agentClientId = agentClientId
+    this._channelId = channelId
+    this._serviceUrl = serviceUrl
+    this._claims = claims
+    this._reference = reference
+  }
+
+  /**
+   * Creates a new builder for the given agent and channel.
+   * @param requestorId Optional: the client ID of the app making the request.
+   *   Becomes the `appid` claim, used in multi-tenant Azure Bot scenarios.
+   */
+  static create (
+    agentClientId: string,
+    channelId: string,
+    serviceUrl?: string,
+    requestorId?: string
+  ): ConversationBuilder {
+    const claims: ConversationClaims = { aud: agentClientId }
+    if (requestorId) claims.appid = requestorId
+    return new ConversationBuilder(agentClientId, channelId, serviceUrl ?? '', claims, ConversationReferenceBuilder.create(agentClientId, channelId, serviceUrl).build())
+  }
+
+  /**
+   * Creates a builder pre-populated from a live `TurnContext`.
+   * Captures both the conversation reference and the JWT identity claims.
+   */
+  static fromContext (context: TurnContext): ConversationBuilder {
+    const ref = context.activity.getConversationReference()
+    const id = context.identity
+    const aud = Array.isArray(id?.aud) ? id.aud[0] : (id?.aud ?? '')
+    const claims: ConversationClaims = {
+      ...(id ?? {}),
+      aud,
+    } as ConversationClaims
+    return new ConversationBuilder(
+      aud,
+      ref.channelId,
+      ref.serviceUrl ?? '',
+      claims,
+      ref
+    )
+  }
+
+  /** Sets `reference.user`. */
+  withUser (userId: string, userName?: string): this {
+    const user: ChannelAccount = { id: userId, name: userName }
+    this._reference = { ...this._reference, user }
+    return this
+  }
+
+  /** Sets `reference.conversation.id`. */
+  withConversationId (id: string): this {
+    const conversation: ConversationAccount = { ...(this._reference.conversation ?? { isGroup: false }), id }
+    this._reference = { ...this._reference, conversation }
+    return this
+  }
+
+  /** Sets `reference.conversation` from a full `ConversationAccount`. */
+  withConversation (account: ConversationAccount): this {
+    this._reference = { ...this._reference, conversation: account }
+    return this
+  }
+
+  /** Sets `reference.activityId`. */
+  withActivityId (activityId: string): this {
+    this._reference = { ...this._reference, activityId }
+    return this
+  }
+
+  /**
+   * Merges a partial `ConversationReference` into the current one.
+   * Useful for overlaying externally-provided reference data without losing
+   * fields set by earlier builder calls.
+   */
+  withReference (ref: Partial<ConversationReference>): this {
+    this._reference = { ...this._reference, ...ref }
+    return this
+  }
+
+  /** Builds the `Conversation`, auto-filling `serviceUrl` from channel defaults if needed. */
+  build (): Conversation {
+    const serviceUrl =
+      this._serviceUrl ||
+      this._reference.serviceUrl ||
+      ConversationReferenceBuilder.serviceUrlForChannel(this._channelId)
+
+    const reference: ConversationReference = {
+      conversation: this._reference.conversation ?? { id: '', isGroup: false },
+      agent: this._reference.agent ?? { id: this._agentClientId },
+      ...this._reference,
+      // Ensure channelId and serviceUrl always use our resolved values
+      channelId: this._channelId,
+      serviceUrl,
+    }
+
+    const conv = new Conversation(this._claims, reference)
+    conv.validate()
+    return conv
+  }
+}

package/src/app/proactive/conversationReferenceBuilder.ts

@@ -0,0 +1,161 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { ChannelAccount, ConversationReference } from '@microsoft/agents-activity'
+import { Channels, RoleTypes } from '@microsoft/agents-activity'
+import { debug } from '@microsoft/agents-telemetry'
+
+const logger = debug('agents:conversation-reference-builder')
+
+/** Set of all channel IDs defined in the Channels enum, used for validation. */
+const knownChannelIds = new Set(Object.values(Channels) as string[])
+
+/**
+ * Well-known Teams service URLs for proactive messaging.
+ *
+ * Use only when the incoming `serviceUrl` from a real conversation is unavailable.
+ * Once you have received a `serviceUrl` from a real turn, cache and prefer that value.
+ */
+export const TeamsServiceEndpoints = {
+  /** Standard public cloud Teams endpoint. */
+  publicGlobal: 'https://smba.trafficmanager.net/teams/',
+  /** US Government Community Cloud (GCC). */
+  gcc: 'https://smba.infra.gcc.teams.microsoft.com/teams',
+  /** US Government Community Cloud High (GCC-High). */
+  gccHigh: 'https://smba.infra.gov.teams.microsoft.us/teams',
+  /** US Department of Defense (DoD). */
+  dod: 'https://smba.infra.dod.teams.microsoft.us/teams',
+} as const
+
+/**
+ * Fluent builder for `ConversationReference`.
+ */
+export class ConversationReferenceBuilder {
+  private readonly _channelId: string
+  private _serviceUrl: string
+  private _agent: ChannelAccount
+  private _user?: ChannelAccount
+  private _conversationId?: string
+  private _activityId?: string
+  private _locale?: string
+
+  private constructor (channelId: string, serviceUrl: string, agent: ChannelAccount) {
+    this._channelId = channelId
+    this._serviceUrl = serviceUrl
+    this._agent = agent
+  }
+
+  /**
+   * Creates a new builder seeded with the agent identity and channel.
+   * On Teams, the agent id is prefixed with `28:` automatically.
+   * @param agentClientId The agent's client (app) ID.
+   * @param channelId The target channel (e.g. `'msteams'`, `'webchat'`).
+   * @param serviceUrl Optional override. If omitted, `build()` fills in the
+   *   channel default via `serviceUrlForChannel()`.
+   */
+  static create (
+    agentClientId: string,
+    channelId: string,
+    serviceUrl?: string
+  ): ConversationReferenceBuilder {
+    return new ConversationReferenceBuilder(
+      channelId,
+      serviceUrl ?? '',
+      ConversationReferenceBuilder.agentForChannel(channelId, agentClientId)
+    )
+  }
+
+  /**
+   * Returns the default service URL for a channel.
+   * Teams returns the public global endpoint; all other channels use the
+   * `https://{channelId}.botframework.com/` pattern (matching C# behavior).
+   */
+  static serviceUrlForChannel (channelId: string): string {
+    if (!channelId) return ''
+    if (channelId === Channels.Msteams) return TeamsServiceEndpoints.publicGlobal
+    if (!knownChannelIds.has(channelId)) {
+      logger.warn(
+        `serviceUrlForChannel: unrecognized channelId '${channelId}' — constructing fallback URL ` +
+        'https://<channelId>.botframework.com/. Provide an explicit serviceUrl to suppress this warning.'
+      )
+    }
+    return `https://${channelId}.botframework.com/`
+  }
+
+  /** Sets `reference.user` from an id + optional name. Role defaults to `RoleTypes.User`. */
+  withUser (userId: string, userName?: string): this
+  /** Sets `reference.user` from a full `ChannelAccount`. */
+  withUser (account: ChannelAccount): this
+  withUser (userIdOrAccount: string | ChannelAccount, userName?: string): this {
+    this._user = typeof userIdOrAccount === 'string'
+      ? { id: userIdOrAccount, name: userName, role: RoleTypes.User }
+      : userIdOrAccount
+    return this
+  }
+
+  /** Sets `reference.agent` from an id + optional name. Role defaults to `RoleTypes.Agent`. On Teams, id is prefixed with `28:`. */
+  withAgent (agentClientId: string, agentName?: string): this
+  /** Sets `reference.agent` from a full `ChannelAccount`. */
+  withAgent (account: ChannelAccount): this
+  withAgent (agentIdOrAccount: string | ChannelAccount, agentName?: string): this {
+    this._agent = typeof agentIdOrAccount === 'string'
+      ? ConversationReferenceBuilder.agentForChannel(this._channelId, agentIdOrAccount, agentName)
+      : agentIdOrAccount
+    return this
+  }
+
+  /** Sets `reference.serviceUrl`. */
+  withServiceUrl (serviceUrl: string): this {
+    this._serviceUrl = serviceUrl
+    return this
+  }
+
+  /** Sets `reference.conversation.id`. */
+  withConversationId (id: string): this {
+    this._conversationId = id
+    return this
+  }
+
+  /** Sets `reference.activityId`. */
+  withActivityId (activityId: string): this {
+    this._activityId = activityId
+    return this
+  }
+
+  /** Sets `reference.locale`. */
+  withLocale (locale: string): this {
+    this._locale = locale
+    return this
+  }
+
+  /** Builds and returns the `ConversationReference`. */
+  build (): ConversationReference {
+    const serviceUrl =
+      this._serviceUrl || ConversationReferenceBuilder.serviceUrlForChannel(this._channelId)
+
+    const ref: ConversationReference = {
+      channelId: this._channelId,
+      serviceUrl,
+      conversation: { id: this._conversationId ?? '', isGroup: false },
+      agent: this._agent,
+      user: this._user ?? { role: RoleTypes.User },
+    }
+
+    if (this._activityId !== undefined) ref.activityId = this._activityId
+    if (this._locale !== undefined) ref.locale = this._locale
+
+    return ref
+  }
+
+  /**
+   * Builds a `ChannelAccount` for the agent, applying the Teams `28:` id prefix
+   * when the channel is `msteams`.
+   */
+  private static agentForChannel (channelId: string, agentClientId: string, agentName?: string): ChannelAccount {
+    return {
+      id: channelId === Channels.Msteams ? `28:${agentClientId}` : agentClientId,
+      name: agentName,
+      role: RoleTypes.Agent,
+    }
+  }
+}

package/src/app/proactive/createConversationOptions.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import type { ConversationParameters } from '@microsoft/agents-activity'
+import type { ConversationClaims } from './conversation'
+
+/**
+ * Default OAuth scope for Azure Bot Service authentication.
+ */
+export const AzureBotScope = 'https://api.botframework.com'
+
+/**
+ * Options passed to `Proactive.createConversation()`.
+ * Flattened — no nested Conversation wrapper.
+ */
+export interface CreateConversationOptions {
+  /** JWT claims for the agent identity. `aud` must be the agent's client ID. */
+  identity: ConversationClaims
+  /** The target channel (e.g. `'msteams'`). */
+  channelId: string
+  /** The service URL for the channel. */
+  serviceUrl: string
+  /**
+   * OAuth scope for token acquisition.
+   * Defaults to `AzureBotScope` when not set by the builder.
+   */
+  scope: string
+  /**
+   * When `true`, the resulting `Conversation` is stored automatically after
+   * creation. Defaults to `false`.
+   */
+  storeConversation?: boolean
+  /** Conversation configuration passed to `adapter.createConversationAsync()`. */
+  parameters: Partial<ConversationParameters>
+}