@microsoft/agents-hosting 1.7.2 → 1.8.0-beta.36.gb033f0abc1

package/src/auth/msal/msalTokenProvider.ts

@@ -15,6 +15,7 @@ import crypto from 'crypto'
 import { AuthenticationTraceDefinitions } from '../../observability'
 import { ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../../errorHelper'
+import { MsalHttpRetryHandlerHelper, normalizeMsalRetryCount } from './msalHttpRetryHandlerHelper'
 
 const audience = 'api://AzureADTokenExchange'
 const logger = debug('agents:msal')
@@ -203,12 +204,14 @@ export class MsalTokenProvider implements AuthProvider {
   }
 
   private getClientSecretClient (authConfig: AuthConfiguration): ConfidentialClientApplication {
+    const retryCount = normalizeMsalRetryCount(authConfig.msalRetryCount)
     const cacheKey = MsalTokenProvider.cacheKey(
       'confidential-client',
       AuthType.ClientSecret,
       authConfig.clientId,
       resolveAuthorityUtil(authConfig.authorityEndpoint ?? authConfig.authority, authConfig.tenantId),
-      MsalTokenProvider.digest(authConfig.clientSecret)
+      MsalTokenProvider.digest(authConfig.clientSecret),
+      retryCount
     )
 
     return this.getOrCreateConfidentialClient(cacheKey, () => new ConfidentialClientApplication({
@@ -217,11 +220,12 @@ export class MsalTokenProvider implements AuthProvider {
         authority: resolveAuthorityUtil(authConfig.authorityEndpoint ?? authConfig.authority, authConfig.tenantId),
         clientSecret: authConfig.clientSecret
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     }))
   }
 
   private getCertificateClient (authConfig: AuthConfiguration): ConfidentialClientApplication {
+    const retryCount = normalizeMsalRetryCount(authConfig.msalRetryCount)
     const cacheKey = MsalTokenProvider.cacheKey(
       'confidential-client',
       authConfig.authType ?? AuthType.Certificate,
@@ -229,7 +233,8 @@ export class MsalTokenProvider implements AuthProvider {
       resolveAuthorityUtil(authConfig.authorityEndpoint ?? authConfig.authority, authConfig.tenantId),
       this.getFileCacheIdentity(authConfig.certPemFile),
       this.getFileCacheIdentity(authConfig.certKeyFile),
-      authConfig.sendX5C
+      authConfig.sendX5C,
+      retryCount
     )
 
     return this.getOrCreateConfidentialClient(cacheKey, () => {
@@ -258,7 +263,7 @@ export class MsalTokenProvider implements AuthProvider {
             x5c: pemFile.toString()
           }
         },
-        system: this.sysOptions
+        system: this.getSystemOptions(authConfig)
       })
     })
   }
@@ -434,7 +439,7 @@ export class MsalTokenProvider implements AuthProvider {
           clientAssertion: appToken,
           authority: this.resolveAuthority(tenantId),
         },
-        system: this.sysOptions
+        system: this.getSystemOptions(this.connectionSettings)
       })
 
       const token = await cca.acquireTokenByClientCredential({
@@ -613,7 +618,7 @@ export class MsalTokenProvider implements AuthProvider {
         managedIdentityIdParams: {
           userAssignedClientId: this.connectionSettings.clientId
         },
-        system: this.sysOptions
+        system: this.getSystemOptions(this.connectionSettings)
       })
       const tokenResult = await msiApp.acquireToken({ resource })
       if (!tokenResult?.accessToken) {
@@ -638,7 +643,10 @@ export class MsalTokenProvider implements AuthProvider {
         if (!this.connectionSettings.federatedClientId && !this.connectionSettings.FICClientId) {
           throw ExceptionHelper.generateException(Error, Errors.FICClientIdRequired)
         }
-        clientAssertion = await this.fetchExternalToken(this.connectionSettings.federatedClientId as string || this.connectionSettings.FICClientId as string)
+        clientAssertion = await this.fetchExternalToken(
+          this.connectionSettings.federatedClientId as string || this.connectionSettings.FICClientId as string,
+          this.connectionSettings
+        )
         break
       case AuthType.Certificate:
       case AuthType.CertificateSubjectName:
@@ -688,6 +696,13 @@ export class MsalTokenProvider implements AuthProvider {
     }
   }
 
+  private getSystemOptions (authConfig?: AuthConfiguration): NodeSystemOptions {
+    return {
+      ...this.sysOptions,
+      networkClient: new MsalHttpRetryHandlerHelper(undefined, normalizeMsalRetryCount(authConfig?.msalRetryCount))
+    }
+  }
+
   /**
    * Generates the client assertion using the provided certificate.
    * @param authConfig The authentication configuration.
@@ -742,7 +757,7 @@ export class MsalTokenProvider implements AuthProvider {
       managedIdentityIdParams: {
         userAssignedClientId: authConfig.clientId || ''
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     })
     const token = await mia.acquireToken({
       resource: scope
@@ -758,7 +773,7 @@ export class MsalTokenProvider implements AuthProvider {
    */
   private async acquireTokenWithSystemAssignedIdentity (authConfig: AuthConfiguration, scope: string) {
     const mia = new ManagedIdentityApplication({
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     })
     const token = await mia.acquireToken({
       resource: scope
@@ -812,14 +827,17 @@ export class MsalTokenProvider implements AuthProvider {
    */
   private async acquireAccessTokenViaFIC (authConfig: AuthConfiguration, scope: string) : Promise<string> {
     const scopes = [`${scope}/.default`]
-    const clientAssertion = await this.fetchExternalToken(authConfig.federatedClientId as string || authConfig.FICClientId as string)
+    const clientAssertion = await this.fetchExternalToken(
+      authConfig.federatedClientId as string || authConfig.FICClientId as string,
+      authConfig
+    )
     const cca = new ConfidentialClientApplication({
       auth: {
         clientId: authConfig.clientId as string,
         authority: `${authConfig.authorityEndpoint ?? authConfig.authority}/${authConfig.tenantId}`,
         clientAssertion
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     })
     const token = await cca.acquireTokenByClientCredential({ scopes, azureRegion: authConfig.azureRegion })
     logger.debug('got token using FIC client assertion')
@@ -845,7 +863,7 @@ export class MsalTokenProvider implements AuthProvider {
         authority: `https://login.microsoftonline.com/${authConfig.tenantId}`,
         clientAssertion
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig)
     })
     const token = await cca.acquireTokenByClientCredential({ scopes, azureRegion: authConfig.azureRegion })
     logger.debug('got token using WID client assertion')
@@ -860,12 +878,12 @@ export class MsalTokenProvider implements AuthProvider {
    * @param FICClientId The FIC client ID.
    * @returns A promise that resolves to the external token.
    */
-  private async fetchExternalToken (FICClientId: string) : Promise<string> {
+  private async fetchExternalToken (FICClientId: string, authConfig?: AuthConfiguration) : Promise<string> {
     const managedIdentityClientAssertion = new ManagedIdentityApplication({
       managedIdentityIdParams: {
         userAssignedClientId: FICClientId
       },
-      system: this.sysOptions
+      system: this.getSystemOptions(authConfig ?? this.connectionSettings)
     }
     )
     const response = await managedIdentityClientAssertion.acquireToken({

package/src/auth/settings.ts

@@ -170,6 +170,12 @@ export function resolveAuthority (authority?: string, tenantId?: string): string
   return `${base}/${tenantId ?? 'botframework.com'}`
 }
 
+function getEffectiveTenant (tenantId: string | undefined, authority: string): string | undefined {
+  const resolvedAuthority = new URL(trimTrailingSlashes(authority))
+  const embeddedTenant = resolvedAuthority.pathname.split('/').filter(Boolean).pop()
+  return embeddedTenant ?? tenantId
+}
+
 function trimTrailingSlashes (value: string): string {
   let end = value.length
   while (end > 0 && value.charCodeAt(end - 1) === 47) {
@@ -179,14 +185,14 @@ function trimTrailingSlashes (value: string): string {
   return end === value.length ? value : value.slice(0, end)
 }
 
-function getDefaultIssuers (tenantId: string, authority: string) : string[] {
+export function getDefaultIssuers (tenantId: string, authority: string) : string[] {
   // Convert empty string to undefined so resolveAuthority applies its 'botframework.com' default
-  const t = tenantId || undefined
+  const t = getEffectiveTenant(tenantId || undefined, authority)
   if (!t) {
     logger.warn('tenantId is not configured, defaulting to botframework.com')
   }
   return [
-    'https://api.botframework.com',
+    /login\.microsoftonline\.us/i.test(authority) ? 'https://api.botframework.us' : 'https://api.botframework.com',
     `${resolveAuthority('https://sts.windows.net', t)}/`,
     `${resolveAuthority(authority, t)}/v2.0`
   ]
@@ -223,6 +229,15 @@ export interface ConnectionSettingsBase {
    */
   issuers?: string[]
 
+  /**
+   * Whether to validate the token issuer against {@link issuers}.
+   *
+   * @remarks
+   * Disabled by default for backward compatibility. Tenant-to-issuer binding is always applied
+   * independently when both claims contain comparable tenant GUIDs.
+   */
+  validateIssuer?: boolean
+
   /**
    * The connection name for the authentication configuration.
    */

package/src/cloudAdapter.ts

@@ -7,7 +7,7 @@ import { AgentHandler, INVOKE_RESPONSE_KEY } from './activityHandler'
 import { BaseAdapter } from './baseAdapter'
 import { TurnContext } from './turnContext'
 import { Request } from './auth/request'
-import { WebResponse } from './interfaces/webResponse'
+import { NextFunction, WebResponse } from './interfaces/webResponse'
 import { ConnectorClient } from './connector-client/connectorClient'
 import { AuthConfiguration, getAuthConfigWithDefaults } from './auth/authConfiguration'
 import { AuthProvider } from './auth/authProvider'
@@ -32,6 +32,8 @@ import { parseBooleanEnv, suggestClosest } from './utils/env'
 import { trace } from '@microsoft/agents-telemetry'
 import { AdapterTraceDefinitions } from './observability'
 import { applyAgenticHeaders } from './getProductInfo'
+import { createOutboundHostValidator, OutboundUrlPolicy } from './outboundHostValidator'
+import { authorizeJWT } from './auth/jwt-middleware'
 
 const logger = debug('agents:cloud-adapter')
 
@@ -80,6 +82,9 @@ export interface CloudAdapterOptions {
    * for one service URL tries to send activities targeting a different one.
    *
    * Env var: `CloudAdapterOptions__validateServiceUrl`.
+   *
+   * @deprecated Configure {@link OutboundUrlPolicy} instead. This option
+   * remains available for backward compatibility with claim-only validation.
    */
   validateServiceUrl?: boolean
 }
@@ -238,6 +243,7 @@ function truncateActivityForLog (activity: unknown, max = 1024): string {
 
 export class CloudAdapter extends BaseAdapter {
   protected readonly authConfig: AuthConfiguration
+  private readonly jwtMiddleware: ReturnType<typeof authorizeJWT>
   protected _agentName?: string
 
   /**
@@ -246,6 +252,7 @@ export class CloudAdapter extends BaseAdapter {
   connectionManager: Connections
 
   private readonly _options: Required<CloudAdapterOptions>
+  private readonly _hostValidator: OutboundUrlPolicy
 
   /**
    * Creates an instance of CloudAdapter.
@@ -253,12 +260,17 @@ export class CloudAdapter extends BaseAdapter {
    * @param authProvider - No longer used.
    * @param userTokenClient - No longer used.
    * @param options - Optional runtime behavior overrides. See {@link CloudAdapterOptions}.
+   * @param outboundHostValidator - Optional policy for validating outbound `Activity.serviceUrl` hosts.
+   * When omitted, the policy is loaded from `OutboundHostValidator__*` environment variables
+   * and remains disabled by default.
    */
-  constructor (authConfig?: AuthConfiguration, authProvider?: AuthProvider, userTokenClient?: UserTokenClient, options?: CloudAdapterOptions) {
+  constructor (authConfig?: AuthConfiguration, authProvider?: AuthProvider, userTokenClient?: UserTokenClient, options?: CloudAdapterOptions, outboundHostValidator?: OutboundUrlPolicy) {
     super()
     this.authConfig = authConfig = getAuthConfigWithDefaults(authConfig)
+    this.jwtMiddleware = authorizeJWT(authConfig)
     this.connectionManager = new MsalConnectionManager(undefined, undefined, authConfig)
     this._options = resolveCloudAdapterOptions(options)
+    this._hostValidator = outboundHostValidator ?? createOutboundHostValidator()
 
     // Install a CloudAdapter-aware default `onTurnError` that honors
     // `emitStackTrace`. The base class default only logs the message; we
@@ -321,6 +333,8 @@ export class CloudAdapter extends BaseAdapter {
     identity: JwtPayload,
     headers?: HeaderPropagationCollection
   ): Promise<ConnectorClient> {
+    this.ensureOutboundServiceUrlAllowed(serviceUrl)
+
     return trace(AdapterTraceDefinitions.createConnectorClient, async ({ record }) => {
       record({ serviceUrl, scopes: [scope] })
 
@@ -349,6 +363,8 @@ export class CloudAdapter extends BaseAdapter {
     identity: JwtPayload,
     activity: Activity,
     headers?: HeaderPropagationCollection) {
+    this.ensureOutboundServiceUrlAllowed(activity.serviceUrl)
+
     return trace(AdapterTraceDefinitions.createConnectorClient, async ({ record }) => {
       if (!identity?.aud) {
         // anonymous
@@ -425,6 +441,24 @@ export class CloudAdapter extends BaseAdapter {
     } as JwtPayload
   }
 
+  /**
+   * Authorizes an incoming web request using this adapter's resolved authentication configuration.
+   * @param req The incoming request.
+   * @param res The outgoing response.
+   * @param next Callback invoked after successful authorization.
+   */
+  public async authorizeRequest (req: Request, res: WebResponse, next: NextFunction): Promise<void> {
+    await this.jwtMiddleware(req, res, next)
+  }
+
+  /**
+   * Gets the client ID used by this adapter's default authentication connection.
+   * @returns The configured client ID, or `undefined` for anonymous development configuration.
+   */
+  public getClientId (): string | undefined {
+    return this.authConfig.clientId
+  }
+
   /**
    * Sets the agent name for M365 agent header propagation.
    * @param agentName The human-friendly agent name to set for header propagation.
@@ -692,6 +726,8 @@ export class CloudAdapter extends BaseAdapter {
    * should be rejected with a 400.
    */
   private validateServiceUrl (identity: JwtPayload | undefined, activity: Activity): boolean {
+    if (!this.isOutboundServiceUrlAllowed(activity.serviceUrl)) return false
+
     if (!identity) return true
     if (!activity.serviceUrl) return true
 
@@ -709,7 +745,7 @@ export class CloudAdapter extends BaseAdapter {
 
     const safeClaim = sanitizeForLog(claimValue)
     const safeServiceUrl = sanitizeForLog(activity.serviceUrl)
-    if (this._options.validateServiceUrl) {
+    if (this._hostValidator.enabled || this._options.validateServiceUrl) {
       logger.error(`Invalid service URL Claim='${safeClaim}', ServiceUrl='${safeServiceUrl}'`)
       return false
     }
@@ -717,6 +753,23 @@ export class CloudAdapter extends BaseAdapter {
     return true
   }
 
+  /**
+   * Applies the shared outbound host policy.
+   */
+  private isOutboundServiceUrlAllowed (serviceUrl: string | undefined): boolean {
+    if (!this._hostValidator.enabled || !serviceUrl || this._hostValidator.isAllowed(serviceUrl)) return true
+
+    logger.warn(`ServiceUrl host is not in the configured allowed hosts. ServiceUrl='${sanitizeForLog(serviceUrl)}'`)
+    return false
+  }
+
+  /** Ensures connector-client creation cannot bypass the outbound host policy. */
+  private ensureOutboundServiceUrlAllowed (serviceUrl: string | undefined): void {
+    if (!this.isOutboundServiceUrlAllowed(serviceUrl)) {
+      throw ExceptionHelper.generateException(Error, Errors.OutboundServiceUrlNotAllowed)
+    }
+  }
+
   /**
    * Updates an activity.
    * @param context - The TurnContext for the current turn.

package/src/errorHelper.ts

@@ -156,6 +156,14 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'serviceUrl must be a non-empty string'
   },
 
+  /**
+    * Error thrown when the outbound service URL is denied by the configured host policy.
+    */
+  OutboundServiceUrlNotAllowed: {
+    code: -120175,
+    description: 'serviceUrl host is not in the configured allowed hosts.'
+  },
+
   /**
      * Error thrown when conversationParameters must be defined.
      */
@@ -416,6 +424,22 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Identity is required to get the token provider.'
   },
 
+  /**
+   * Error thrown when an MSAL HTTP request cannot be completed.
+   */
+  MsalHttpRequestFailed: {
+    code: -120391,
+    description: 'MSAL HTTP request failed: {message}'
+  },
+
+  /**
+   * Error thrown when an MSAL HTTP response body cannot be parsed as JSON.
+   */
+  MsalResponseUnparsable: {
+    code: -120392,
+    description: 'MSAL returned an unparsable response body'
+  },
+
   FailedToAcquireTokenUsingCertificate: {
     code: -120395,
     description: 'Failed to acquire token using certificate'
@@ -673,108 +697,6 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Token request timed out after {timeoutMs} ms'
   },
 
-  // ============================================================================
-  // Entra Agent ID Sidecar Authentication Errors (-120800 to -120849)
-  // ============================================================================
-
-  /**
-   * Error thrown when the Entra sidecar auth provider is used without connection settings.
-   */
-  SidecarConnectionSettingsRequired: {
-    code: -120800,
-    description: 'Connection settings must be provided when using the Entra sidecar auth provider'
-  },
-
-  /**
-   * Error thrown when the resolved sidecar base URL is not a valid absolute URL.
-   */
-  SidecarBaseUrlInvalid: {
-    code: -120801,
-    description: 'The resolved sidecar base URL `{url}` is not a valid absolute URL'
-  },
-
-  /**
-   * Error thrown when the resolved sidecar base URL does not use the http or https scheme.
-   */
-  SidecarBaseUrlInsecureScheme: {
-    code: -120802,
-    description: 'The resolved sidecar base URL `{url}` must use the http or https scheme'
-  },
-
-  /**
-   * Error thrown when the resolved sidecar base URL contains userinfo (credentials).
-   */
-  SidecarBaseUrlUserInfo: {
-    code: -120803,
-    description: 'The resolved sidecar base URL `{url}` must not contain userinfo (credentials)'
-  },
-
-  /**
-   * Error thrown when the resolved sidecar base URL points to a non-loopback, non-private address.
-   */
-  SidecarBaseUrlNotLocal: {
-    code: -120804,
-    description: 'The resolved sidecar base URL `{url}` points to a non-loopback, non-private address. The Entra Agent ID sidecar (agent container) must be reachable only from within the agent\'s network boundary. Set `bypassLocalNetworkRestriction` to true in the connection configuration to override this safety check (UNSAFE: only for carefully validated private-network configurations)'
-  },
-
-  /**
-   * Error thrown when both AgentUsername and AgentUserId are supplied on a sidecar request (mutually exclusive).
-   */
-  SidecarUserIdentityMutuallyExclusive: {
-    code: -120805,
-    description: 'AgentUsername and AgentUserId are mutually exclusive; set only one on the sidecar request options'
-  },
-
-  /**
-   * Error thrown when a sidecar request fails after exhausting all retry attempts.
-   */
-  SidecarRequestFailed: {
-    code: -120806,
-    description: 'Sidecar request failed after {attempts} attempt(s): {message}'
-  },
-
-  /**
-   * Error thrown when the sidecar responds with a non-success status code.
-   */
-  SidecarErrorResponse: {
-    code: -120807,
-    description: 'Sidecar returned error status {status}: {message}'
-  },
-
-  /**
-   * Error thrown when the sidecar response is missing the authorizationHeader field.
-   */
-  SidecarResponseMissingAuthorizationHeader: {
-    code: -120808,
-    description: 'Sidecar response missing `authorizationHeader` field'
-  },
-
-  /**
-   * Error thrown when the sidecar response body cannot be parsed.
-   */
-  SidecarResponseUnparsable: {
-    code: -120809,
-    description: 'Sidecar returned an unparsable response body'
-  },
-
-  /**
-   * Error thrown when acquireTokenOnBehalfOf is called on the sidecar provider, which does not support OBO in Phase 1.
-   */
-  OnBehalfOfNotSupportedBySidecar: {
-    code: -120810,
-    description: 'acquireTokenOnBehalfOf is not supported by the Entra sidecar auth provider in Phase 1'
-  },
-
-  /**
-   * Error thrown when the sidecar returns a token with an authorization scheme other than Bearer.
-   * The hosting stack always transmits tokens as `Bearer {token}`, so a non-Bearer scheme cannot be
-   * honored and is rejected rather than silently sent as an invalid Authorization header.
-   */
-  SidecarUnsupportedAuthScheme: {
-    code: -120811,
-    description: 'The Entra Agent ID sidecar returned an unsupported authorization scheme `{scheme}`. Only the Bearer scheme is supported'
-  },
-
   // ============================================================================
   // Agent and Client Errors (-120600 to -120650)
   // ============================================================================
@@ -1012,32 +934,105 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
   },
 
   // ============================================================================
-  // Hosting / Web layer errors (-120800 to -120840)
+  // Entra Agent ID Sidecar Authentication Errors (-120800 to -120811)
   // ============================================================================
 
   /**
-   * Error thrown by CloudAdapter.process when the incoming request lacks a parsed body.
-   * Indicates the hosting layer (e.g. express.json() or Fastify's JSON parser) was not configured.
+   * Error thrown when the Entra sidecar auth provider is used without connection settings.
    */
-  MissingRequestBody: {
+  SidecarConnectionSettingsRequired: {
     code: -120800,
-    description: '`request.body` parameter required; ensure your hosting layer parses JSON request bodies before invoking the adapter (e.g., express.json() with Express or Fastify\'s built-in JSON parser).'
+    description: 'Connection settings must be provided when using the Entra sidecar auth provider'
   },
 
   /**
-   * Error thrown by verifyToken when the provided JWT cannot be decoded.
+   * Error thrown when the resolved sidecar base URL is not a valid absolute URL.
    */
-  InvalidJwtToken: {
+  SidecarBaseUrlInvalid: {
+    code: -120801,
+    description: 'The resolved sidecar base URL `{url}` is not a valid absolute URL'
+  },
+
+  /**
+   * Error thrown when the resolved sidecar base URL does not use the http or https scheme.
+   */
+  SidecarBaseUrlInsecureScheme: {
+    code: -120802,
+    description: 'The resolved sidecar base URL `{url}` must use the http or https scheme'
+  },
+
+  /**
+   * Error thrown when the resolved sidecar base URL contains userinfo (credentials).
+   */
+  SidecarBaseUrlUserInfo: {
+    code: -120803,
+    description: 'The resolved sidecar base URL `{url}` must not contain userinfo (credentials)'
+  },
+
+  /**
+   * Error thrown when the resolved sidecar base URL points to a non-loopback, non-private address.
+   */
+  SidecarBaseUrlNotLocal: {
+    code: -120804,
+    description: 'The resolved sidecar base URL `{url}` points to a non-loopback, non-private address. The Entra Agent ID sidecar (agent container) must be reachable only from within the agent\'s network boundary. Set `bypassLocalNetworkRestriction` to true in the connection configuration to override this safety check (UNSAFE: only for carefully validated private-network configurations)'
+  },
+
+  /**
+   * Error thrown when both AgentUsername and AgentUserId are supplied on a sidecar request (mutually exclusive).
+   */
+  SidecarUserIdentityMutuallyExclusive: {
+    code: -120805,
+    description: 'AgentUsername and AgentUserId are mutually exclusive; set only one on the sidecar request options'
+  },
+
+  /**
+   * Error thrown when a sidecar request fails after exhausting all retry attempts.
+   */
+  SidecarRequestFailed: {
+    code: -120806,
+    description: 'Sidecar request failed after {attempts} attempt(s): {message}'
+  },
+
+  /**
+   * Error thrown when the sidecar responds with a non-success status code.
+   */
+  SidecarErrorResponse: {
+    code: -120807,
+    description: 'Sidecar returned error status {status}: {message}'
+  },
+
+  /**
+   * Error thrown when the sidecar response is missing the authorizationHeader field.
+   */
+  SidecarResponseMissingAuthorizationHeader: {
+    code: -120808,
+    description: 'Sidecar response missing `authorizationHeader` field'
+  },
+
+  /**
+   * Error thrown when the sidecar response body cannot be parsed.
+   */
+  SidecarResponseUnparsable: {
+    code: -120809,
+    description: 'Sidecar returned an unparsable response body'
+  },
+
+  /**
+   * Error thrown when acquireTokenOnBehalfOf is called on the sidecar provider, which does not support OBO in Phase 1.
+   */
+  OnBehalfOfNotSupportedBySidecar: {
     code: -120810,
-    description: 'invalid token'
+    description: 'acquireTokenOnBehalfOf is not supported by the Entra sidecar auth provider in Phase 1'
   },
 
   /**
-   * Error thrown by verifyToken when the token audience does not match any configured connection clientId.
+   * Error thrown when the sidecar returns a token with an authorization scheme other than Bearer.
+   * The hosting stack always transmits tokens as `Bearer {token}`, so a non-Bearer scheme cannot be
+   * honored and is rejected rather than silently sent as an invalid Authorization header.
    */
-  JwtAudienceMismatch: {
-    code: -120820,
-    description: 'Audience mismatch'
+  SidecarUnsupportedAuthScheme: {
+    code: -120811,
+    description: 'The Entra Agent ID sidecar returned an unsupported authorization scheme `{scheme}`. Only the Bearer scheme is supported'
   },
 
   // ============================================================================
@@ -1102,6 +1097,52 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: "You must configure the Application with an 'adapter' before calling Application.continueConversationAsync()"
   },
 
+  // ============================================================================
+  // Hosting / Web layer errors (-120910 to -120940)
+  // ============================================================================
+
+  /**
+   * Error thrown by CloudAdapter.process when the incoming request lacks a parsed body.
+   * Indicates the hosting layer (e.g. express.json() or Fastify's JSON parser) was not configured.
+   */
+  MissingRequestBody: {
+    code: -120910,
+    description: '`request.body` parameter required; ensure your hosting layer parses JSON request bodies before invoking the adapter (e.g., express.json() with Express or Fastify\'s built-in JSON parser).'
+  },
+
+  /**
+   * Error thrown by verifyToken when the provided JWT cannot be decoded.
+   */
+  InvalidJwtToken: {
+    code: -120920,
+    description: 'invalid token'
+  },
+
+  /**
+   * Error thrown by verifyToken when the token audience does not match any configured connection clientId.
+   */
+  JwtAudienceMismatch: {
+    code: -120930,
+    description: 'Audience mismatch'
+  },
+
+  /**
+   * Error thrown by verifyToken when the token issuer is not in the connection's allowed issuer list.
+   */
+  JwtIssuerMismatch: {
+    code: -120830,
+    description: 'Issuer mismatch'
+  },
+
+  /**
+   * Error thrown by verifyToken when an Entra token's tenant id (`tid`) claim does not match the
+   * tenant GUID embedded in its issuer (`iss`) claim.
+   */
+  JwtTenantMismatch: {
+    code: -120840,
+    description: 'Tenant mismatch'
+  },
+
   // ============================================================================
   // Adaptive Cards Errors (-120950 to -120980)
   // ============================================================================

package/src/index.ts

@@ -32,5 +32,6 @@ export * from './storage/storage'
 export * from './headerPropagation'
 export * from './interfaces'
 export * from './httpClient'
+export * from './outboundHostValidator'
 
 export * from './agent-client'

package/src/invoke/adaptiveCardInvokeValue.ts

@@ -22,4 +22,9 @@ export interface AdaptiveCardInvokeValue {
    * The state of the adaptive card.
    */
   state: string
+  /**
+   * Indicates whether Teams initiated the action while rendering a refreshable
+   * card or a user explicitly selected an action.
+   */
+  trigger?: 'automatic' | 'manual'
 }