@microsoft/agents-hosting 1.7.1 → 1.8.0-beta.34.g5d543f96c0

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'
 }

package/src/oauth/userTokenClient.ts

@@ -80,7 +80,6 @@ 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.

package/src/observability/traces.ts

@@ -26,7 +26,8 @@ export const AgentApplicationTraceDefinitions = {
       span.setAttributes({
         'route.authorized': record.authorized,
         'route.matched': record.routeMatched,
-        ...attributes
+        ...attributes,
+        'activity.name': activity.name ?? 'unknown'
       })
 
       HostingMetrics.turnsTotalCounter.add(1, attributes)

package/src/outboundHostValidator.ts

@@ -0,0 +1,172 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { parseBooleanEnv } from './utils/env'
+
+/** Hosts used by Microsoft channel callbacks and hosted attachments. */
+const DEFAULT_MICROSOFT_HOSTS = Object.freeze([
+  'botframework.com',
+  'smba.trafficmanager.net',
+  'teams.microsoft.com',
+  'teams.microsoft.us',
+  'graph.microsoft.com',
+  'sharepoint.com',
+  'svc.ms',
+  'blob.core.windows.net'
+])
+
+const OUTBOUND_HOST_VALIDATOR_ENV_PREFIX = 'OutboundHostValidator__'
+const OUTBOUND_HOST_VALIDATOR_ENV_PREFIX_UPPER = OUTBOUND_HOST_VALIDATOR_ENV_PREFIX.toUpperCase()
+
+/** Configuration for the shared outbound-host allowlist. */
+export interface OutboundHostValidatorOptions {
+  /** Enables allowlist enforcement. Defaults to `false`. */
+  enabled?: boolean
+
+  /**
+   * Indicates whether the built-in list of Microsoft first-party hosts
+   * (Bot Connector, Graph, SharePoint, Azure Blob/AMS) is included when enforcement is enabled.
+   * Defaults to `true`.
+   */
+  includeDefaultMicrosoftHosts?: boolean
+
+  /** Additional exact hosts or host suffixes to allow.
+   * An entry matches a request host when the host equals the entry or is a subdomain of it (e.g. `contoso.com` matches `contoso.com` and `files.contoso.com`).
+   * A leading `*.` is accepted and ignored (treated as a suffix). Ports and paths are ignored if provided.
+   */
+  hosts?: readonly string[]
+}
+
+/** A policy that decides whether an outbound URL is safe to request. */
+export interface OutboundUrlPolicy {
+  readonly enabled: boolean
+  isAllowed(url: string | URL | null | undefined): boolean
+}
+
+/**
+ * Shared allowlist policy for server-side outbound requests.
+ *
+ * A configured suffix matches both the exact host and its subdomains. The
+ * policy is disabled by default to preserve existing SDK behavior.
+ */
+export class OutboundHostValidator implements OutboundUrlPolicy {
+  public readonly enabled: boolean
+  private readonly suffixes: ReadonlySet<string>
+
+  public constructor (options: OutboundHostValidatorOptions = {}) {
+    this.enabled = options.enabled ?? false
+
+    const suffixes = new Set<string>()
+    if (options.includeDefaultMicrosoftHosts ?? true) {
+      for (const host of DEFAULT_MICROSOFT_HOSTS) suffixes.add(host)
+    }
+
+    for (const host of options.hosts ?? []) {
+      const normalized = normalizeConfiguredHost(host)
+      if (normalized) suffixes.add(normalized)
+    }
+
+    this.suffixes = suffixes
+  }
+
+  public isAllowed (input: string | URL | null | undefined): boolean {
+    if (!this.enabled) return true
+
+    const host = getUrlHost(input)
+    if (!host) return false
+
+    for (const suffix of this.suffixes) {
+      if (host === suffix || host.endsWith(`.${suffix}`)) return true
+    }
+
+    return false
+  }
+}
+
+/**
+ * Loads validator options from environment variables compatible with the
+ * .NET `OutboundHostValidator` configuration section.
+ *
+ * Hosts can be supplied either as a comma-separated `Hosts` value or as
+ * indexed values such as `Hosts__0`, `Hosts__1`, and so on.
+ */
+export function loadOutboundHostValidatorOptionsFromEnv (): OutboundHostValidatorOptions {
+  const result: OutboundHostValidatorOptions = {}
+  const indexedHosts = new Map<number, string>()
+  const hosts: string[] = []
+
+  for (const [envKey, rawValue] of Object.entries(process.env)) {
+    const upperKey = envKey.toUpperCase()
+    if (!upperKey.startsWith(OUTBOUND_HOST_VALIDATOR_ENV_PREFIX_UPPER)) continue
+
+    const property = envKey.substring(OUTBOUND_HOST_VALIDATOR_ENV_PREFIX.length)
+    const upperProperty = property.toUpperCase()
+
+    if (upperProperty === 'ENABLED') {
+      const value = parseBooleanEnv(rawValue)
+      if (value !== undefined) result.enabled = value
+    } else if (upperProperty === 'INCLUDEDEFAULTMICROSOFTHOSTS') {
+      const value = parseBooleanEnv(rawValue)
+      if (value !== undefined) result.includeDefaultMicrosoftHosts = value
+    } else if (upperProperty === 'HOSTS' && rawValue) {
+      hosts.push(...rawValue.split(',').map(host => host.trim()).filter(Boolean))
+    } else {
+      const match = /^HOSTS__(\d+)$/i.exec(property)
+      if (match && rawValue?.trim()) indexedHosts.set(Number(match[1]), rawValue.trim())
+    }
+  }
+
+  for (const [, host] of [...indexedHosts.entries()].sort(([left], [right]) => left - right)) {
+    hosts.push(host)
+  }
+  if (hosts.length > 0) result.hosts = hosts
+
+  return result
+}
+
+/** Creates the default validator, with explicit settings overriding the environment. */
+export function createOutboundHostValidator (options?: OutboundHostValidatorOptions): OutboundHostValidator {
+  const fromEnv = loadOutboundHostValidatorOptionsFromEnv()
+  return new OutboundHostValidator({
+    enabled: options?.enabled ?? fromEnv.enabled,
+    includeDefaultMicrosoftHosts: options?.includeDefaultMicrosoftHosts ?? fromEnv.includeDefaultMicrosoftHosts,
+    hosts: options?.hosts ?? fromEnv.hosts
+  })
+}
+
+function getUrlHost (input: string | URL | null | undefined): string | undefined {
+  if (!input) return undefined
+
+  try {
+    const url = input instanceof URL ? input : new URL(input)
+    return normalizeHostname(url.hostname)
+  } catch {
+    return undefined
+  }
+}
+
+function normalizeConfiguredHost (input: string): string | undefined {
+  let candidate = input?.trim()
+  if (!candidate) return undefined
+  if (candidate.startsWith('*.')) candidate = candidate.slice(2)
+
+  try {
+    const absolute = new URL(candidate)
+    if (absolute.hostname) return normalizeHostname(absolute.hostname)
+  } catch {
+    // A bare host, host:port, or host/path is handled below.
+  }
+
+  try {
+    return normalizeHostname(new URL(`http://${candidate}`).hostname)
+  } catch {
+    return undefined
+  }
+}
+
+function normalizeHostname (host: string): string | undefined {
+  const normalized = host.trim().toLowerCase().replace(/\.$/, '')
+  return normalized || undefined
+}

package/src/state/agentState.ts

@@ -44,7 +44,10 @@ export interface CustomKey {
    * The ID of the conversation where the state should be stored
    */
   conversationId: string;
-  // TODO: namespace needs to be added
+  /**
+   * Optional namespace appended to the generated storage key
+   */
+  namespace?: string;
 }
 
 /**
@@ -152,8 +155,10 @@ export class AgentState {
   private async getStorageOrCustomKey (customKey: CustomKey | undefined, context: TurnContext) {
     let key: string | undefined
     if (customKey && customKey.channelId && customKey.conversationId) {
-      // TODO check ConversationState.ts line 40. This line below should follow the same pattern
-      key = `${customKey!.channelId}/conversations/${customKey!.conversationId}`
+      key = `${customKey.channelId}/conversations/${customKey.conversationId}`
+      if (customKey.namespace) {
+        key = `${key}/${customKey.namespace}`
+      }
     } else {
       key = await this.storageKey(context)
     }
@@ -217,13 +222,26 @@ export class AgentState {
    */
   private readonly calculateChangeHash = (item: StoreItem): string => {
     const { eTag, ...rest } = item
-
-    // TODO review circular json structure
-    const result = JSON.stringify(rest)
+    const result = this.stringifyForHash(rest)
 
     const hash = createHash('sha256', { encoding: 'utf-8' })
     const hashed = hash.update(result).digest('hex')
 
     return hashed
   }
+
+  private readonly stringifyForHash = (item: StoreItem): string => {
+    const seen = new WeakSet<object>()
+
+    return JSON.stringify(item, (_key, value) => {
+      if (value && typeof value === 'object') {
+        if (seen.has(value)) {
+          return '[Circular]'
+        }
+        seen.add(value)
+      }
+
+      return value
+    })
+  }
 }