@microsoft/agents-hosting 1.10.0-beta.8.g158a2c07ad → 1.10.1

package/src/app/teamsAttachmentDownloader.ts

@@ -12,17 +12,26 @@ import { TurnState } from './turnState'
 import { HttpClient } from '../httpClient'
 import { z } from 'zod'
 import { createOutboundHostValidator, OutboundUrlPolicy } from '../outboundHostValidator'
+import { AttachmentDownloadHttpClient } from './attachmentDownloadHttpClient'
 
 const logger = debug('agents:M365AttachmentDownloader')
 
 /**
  * Downloads attachments from Teams and M365 using the bots access token.
+ * Enabled outbound validation requires HTTPS and validates addresses at every redirect.
+ * Initial request credentials are not forwarded to redirects when validation is enabled.
  */
 export class M365AttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
   private _httpClient: HttpClient
   private _stateKey: string
   private readonly _hostValidator: OutboundUrlPolicy
 
+  /**
+   * Creates an attachment downloader.
+   *
+   * @param stateKey - Turn-state key used by {@link downloadAndStoreFiles}.
+   * @param outboundHostValidator - Policy used to validate attachment download URLs.
+   */
   public constructor (stateKey: string = 'inputFiles', outboundHostValidator?: OutboundUrlPolicy) {
     this._httpClient = new HttpClient()
     this._stateKey = stateKey
@@ -46,11 +55,11 @@ export class M365AttachmentDownloader<TState extends TurnState = TurnState> impl
     }
 
     const connectorClient : ConnectorClient = context.turnState.get<ConnectorClient>(context.adapter.ConnectorClientKey)
-    this._httpClient.defaultHeaders = { ...connectorClient.httpClient.defaultHeaders }
+    const headers = { ...connectorClient.httpClient.defaultHeaders }
 
     const files: InputFile[] = []
     for (const attachment of attachments) {
-      const file = await this.downloadFile(attachment)
+      const file = await this.downloadFile(attachment, headers)
       if (file) {
         files.push(file)
       }
@@ -64,7 +73,7 @@ export class M365AttachmentDownloader<TState extends TurnState = TurnState> impl
    * @param {Attachment} attachment - Attachment to download.
    * @returns {Promise<InputFile>} - Promise that resolves to the downloaded input file.
    */
-  private async downloadFile (attachment: Attachment): Promise<InputFile | undefined> {
+  private async downloadFile (attachment: Attachment, headers: Record<string, string> = {}): Promise<InputFile | undefined> {
     let inputFile: InputFile | undefined
 
     if (attachment.contentUrl && attachment.contentUrl.startsWith('https://')) {
@@ -72,21 +81,19 @@ export class M365AttachmentDownloader<TState extends TurnState = TurnState> impl
         const contentSchema = z.object({ downloadUrl: z.string().url() })
         const parsed = contentSchema.safeParse(attachment.content)
         const downloadUrl = parsed.success ? parsed.data.downloadUrl : attachment.contentUrl
-        if (!this._hostValidator.isAllowed(downloadUrl)) {
-          let host = '[invalid-url]'
-          try { host = new URL(downloadUrl).hostname } catch { /* invalid */ }
-          logger.warn(`Attachment downloadUrl host is not in the configured allowed hosts. Host='${host}'`)
+        const response = await new AttachmentDownloadHttpClient(this._httpClient, this._hostValidator)
+          .get(downloadUrl, headers)
+        if (!response) {
           return undefined
         }
 
-        const response = await this._httpClient.get(downloadUrl, { responseType: 'arraybuffer' })
-
         const content = Buffer.from(response.data as ArrayBuffer)
         const contentTypeHeader = response.headers.get('content-type')
         const contentType = typeof contentTypeHeader === 'string' ? contentTypeHeader : 'application/octet-stream'
         inputFile = { content, contentType, contentUrl: attachment.contentUrl }
       } catch (error) {
-        logger.error(`Failed to download Teams attachment: ${error}`)
+        const code = error instanceof Error && 'code' in error && typeof error.code === 'number' ? error.code : 'unavailable'
+        logger.error(`Failed to download Teams attachment. Error type='${error instanceof Error ? error.name : 'unknown'}', Code='${code}'`)
         return undefined
       }
     } else {

package/src/auth/authConfiguration.ts

@@ -441,6 +441,7 @@ let globalEnv = loadEnv()
  * Optional host-scoped inputs used while resolving authentication settings.
  */
 export interface AuthConfigurationResolutionOptions {
+  /** Host-scoped configuration layers to include during resolution. */
   configurationContext?: ConfigurationContext
 }
 

package/src/auth/authConstants.ts

@@ -2,10 +2,17 @@
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */
+/** APX OAuth scope for local development. */
 export const ApxLocalScope: string = 'c16e153d-5d2b-4c21-b7f4-b05ee5d516f1/.default'
+/** APX OAuth scope for the development environment. */
 export const ApxDevScope: string = '0d94caae-b412-4943-8a68-83135ad6d35f/.default'
+/** APX OAuth scope for the production environment. */
 export const ApxProductionScope: string = '5a807f24-c9de-44ee-a3a7-329e88a00ffc/.default'
+/** APX OAuth scope for the US Government Community Cloud environment. */
 export const ApxGCCScope: string = 'c9475445-9789-4fef-9ec5-cde4a9bcd446/.default'
+/** APX OAuth scope for the US Government Community Cloud High environment. */
 export const ApxGCCHScope: string = '6f669b9e-7701-4e2b-b624-82c9207fde26/.default'
+/** APX OAuth scope for the US Department of Defense environment. */
 export const ApxDoDScope: string = '0a069c81-8c7c-4712-886b-9c542d673ffb/.default'
+/** APX OAuth scope for the Microsoft Cloud operated by 21Vianet. */
 export const ApxGallatinScope: string = 'bd004c8e-5acf-4c48-8570-4e7d46b2f63b/.default'

package/src/auth/authProvider.ts

@@ -21,7 +21,20 @@ export interface AuthProvider {
    * @returns A promise that resolves to the access token.
    */
   getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string>
+  /**
+   * Gets an access token using this provider's connection settings.
+   *
+   * @param scope - Scope for which the access token is requested.
+   * @returns A promise that resolves to the access token.
+   */
   getAccessToken (scope: string): Promise<string>
+  /**
+   * Gets an access token using explicit or provider-level settings.
+   *
+   * @param authConfigOrScope - Authentication configuration, or the scope when using provider settings.
+   * @param scope - Scope used with an explicit authentication configuration.
+   * @returns A promise that resolves to the access token.
+   */
   getAccessToken (authConfigOrScope: AuthConfiguration | string, scope?: string): Promise<string>
 
   /**
@@ -50,8 +63,31 @@ export interface AuthProvider {
    */
   getAgenticUserToken: (tenantId: string, agentAppInstanceId: string, upn: string, scopes: string[]) => Promise<string>
 
+  /**
+   * Acquires a token on behalf of a user using this provider's connection settings.
+   *
+   * @param scopes - Scopes requested for the delegated token.
+   * @param oboAssertion - User assertion exchanged for the token.
+   * @returns A promise that resolves to the delegated access token.
+   */
   acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+  /**
+   * Acquires a token on behalf of a user using explicit authentication settings.
+   *
+   * @param authConfig - Authentication configuration.
+   * @param scopes - Scopes requested for the delegated token.
+   * @param oboAssertion - User assertion exchanged for the token.
+   * @returns A promise that resolves to the delegated access token.
+   */
   acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
+  /**
+   * Acquires a delegated token using explicit or provider-level settings.
+   *
+   * @param authConfigOrScopes - Authentication configuration, or requested scopes when using provider settings.
+   * @param scopesOrOboAssertion - Requested scopes or the user assertion, depending on the overload.
+   * @param oboAssertion - User assertion used with explicit authentication settings.
+   * @returns A promise that resolves to the delegated access token.
+   */
   acquireTokenOnBehalfOf (
     authConfigOrScopes: AuthConfiguration | string[],
     scopesOrOboAssertion?: string[] | string,

package/src/auth/connectionManager.ts

@@ -146,7 +146,9 @@ export class ConnectionManager implements Connections {
       audience = identity.aud
     }
 
-    if (!audience || !serviceUrl) throw ExceptionHelper.generateException(Error, Errors.AudienceAndServiceUrlRequiredForTokenProvider)
+    if (!audience || !serviceUrl) {
+      throw ExceptionHelper.generateException(Error, Errors.AudienceAndServiceUrlRequiredForTokenProvider)
+    }
 
     if (this._connectionsMap.length === 0) {
       logger.debug('no connectionsMap, using default connection for serviceUrl=%s', serviceUrl)

package/src/auth/connections.ts

@@ -8,6 +8,7 @@ import { AuthConfiguration } from './authConfiguration'
 import { AuthProvider } from './authProvider'
 import { JwtPayload } from 'jsonwebtoken'
 
+/** Provides configured authentication connections and token providers. */
 export interface Connections {
   /**
  * Get the OAuth connection for the agent.

package/src/auth/msal/msalConnectionManager.ts

@@ -14,6 +14,13 @@ import { ConnectionManager, defaultAuthProviderFactory } from '../connectionMana
  * provider factory and applies MSAL-specific connection defaults.
  */
 export class MsalConnectionManager extends ConnectionManager {
+  /**
+   * Creates an MSAL connection manager.
+   *
+   * @param connectionsConfigurations - Authentication settings keyed by connection name.
+   * @param connectionsMap - Rules that map service URLs and audiences to connections.
+   * @param configuration - Default authentication configuration.
+   */
   constructor (
     connectionsConfigurations: Map<string, AuthConfiguration> = new Map(),
     connectionsMap: ConnectionMapItem[] = [],

package/src/auth/msal/msalTokenProvider.ts

@@ -37,8 +37,14 @@ export class MsalTokenProvider implements AuthProvider {
   private static readonly _agenticTokenCache = new MemoryCache<string>()
   private static readonly _confidentialClients = new Map<string, ConfidentialClientApplication>()
   private static readonly _maxConfidentialClients = 100
+  /** Authentication settings used by overloads that do not accept an explicit configuration. */
   public readonly connectionSettings?: AuthConfiguration
 
+  /**
+   * Creates an MSAL token provider.
+   *
+   * @param connectionSettings - Default authentication settings for token acquisition.
+   */
   constructor (connectionSettings?: AuthConfiguration) {
     this.connectionSettings = connectionSettings
   }
@@ -281,6 +287,13 @@ export class MsalTokenProvider implements AuthProvider {
    * @returns A promise that resolves to the access token.
    */
   public async getAccessToken (authConfig: AuthConfiguration, scope: string): Promise<string>
+  /**
+   * Gets an access token using explicit or provider-level settings.
+   *
+   * @param authConfigOrScope - Authentication configuration, or the scope when using provider settings.
+   * @param scope - Scope used with an explicit authentication configuration.
+   * @returns The access token.
+   */
   public async getAccessToken (authConfigOrScope: AuthConfiguration | string, scope?: string): Promise<string> {
     return trace(AuthenticationTraceDefinitions.getAccessToken, async ({ record }) => {
       let authConfig: AuthConfiguration
@@ -368,8 +381,31 @@ export class MsalTokenProvider implements AuthProvider {
     })
   }
 
+  /**
+   * Acquires a delegated token using this provider's connection settings.
+   *
+   * @param scopes - Scopes requested for the delegated token.
+   * @param oboAssertion - User assertion exchanged for the token.
+   * @returns The delegated access token.
+   */
   public async acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+  /**
+   * Acquires a delegated token using explicit authentication settings.
+   *
+   * @param authConfig - Authentication configuration.
+   * @param scopes - Scopes requested for the delegated token.
+   * @param oboAssertion - User assertion exchanged for the token.
+   * @returns The delegated access token.
+   */
   public async acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
+  /**
+   * Acquires a delegated token using explicit or provider-level settings.
+   *
+   * @param authConfigOrScopes - Authentication configuration, or requested scopes when using provider settings.
+   * @param scopesOrOboAssertion - Requested scopes or the user assertion, depending on the overload.
+   * @param oboAssertion - User assertion used with explicit authentication settings.
+   * @returns The delegated access token.
+   */
   public async acquireTokenOnBehalfOf (
     authConfigOrScopes: AuthConfiguration | string[],
     scopesOrOboAssertion?: string[] | string,
@@ -411,6 +447,13 @@ export class MsalTokenProvider implements AuthProvider {
     })
   }
 
+  /**
+   * Gets a federated token for an agent application instance.
+   *
+   * @param tenantId - Microsoft Entra tenant ID.
+   * @param agentAppInstanceId - Agent application instance ID.
+   * @returns The agent instance token.
+   */
   public async getAgenticInstanceToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
     return trace(AuthenticationTraceDefinitions.getAgenticInstanceToken, async ({ record }) => {
       logger.debug('getAgenticInstanceToken tenantId=%s agentAppInstanceId=%s', tenantId, agentAppInstanceId)
@@ -566,6 +609,15 @@ export class MsalTokenProvider implements AuthProvider {
     return token.access_token
   }
 
+  /**
+   * Gets a delegated token for an agentic user.
+   *
+   * @param tenantId - Microsoft Entra tenant ID.
+   * @param agentAppInstanceId - Agent application instance ID.
+   * @param agenticUserId - ID of the user represented by the token.
+   * @param scopes - Scopes requested for the token.
+   * @returns The agentic user token.
+   */
   public async getAgenticUserToken (tenantId: string, agentAppInstanceId: string, agenticUserId: string, scopes: string[]): Promise<string> {
     return trace(AuthenticationTraceDefinitions.getAgenticUserToken, async ({ record }) => {
       logger.debug('getAgenticUserToken tenantId=%s agentAppInstanceId=%s scopes=%o', tenantId, agentAppInstanceId, scopes)
@@ -597,6 +649,13 @@ export class MsalTokenProvider implements AuthProvider {
     })
   }
 
+  /**
+   * Gets the application token used to authenticate an agent application instance.
+   *
+   * @param tenantId - Microsoft Entra tenant ID.
+   * @param agentAppInstanceId - Agent application instance ID.
+   * @returns The agentic application token.
+   */
   public async getAgenticApplicationToken (tenantId: string, agentAppInstanceId: string): Promise<string> {
     if (!this.connectionSettings?.clientId) {
       throw ExceptionHelper.generateException(Error, Errors.ConnectionSettingsRequiredForGetAgenticApplicationToken)

package/src/auth/settings.ts

@@ -24,16 +24,28 @@ const AUTHORITY_DEFAULT = 'https://login.microsoftonline.com'
  * (matched by audience and/or serviceUrl) to a named connection.
  */
 export interface ConnectionMapItem {
+  /** Service URL pattern matched by this route. */
   serviceUrl: string
+  /** Optional token audience matched by this route. */
   audience?: string
+  /** Name of the connection selected by this route. */
   connection: string
 }
 
+/** Default route that selects the standard service connection. */
 export const DEFAULT_CONNECTION_MAP: ConnectionMapItem = { serviceUrl: '*', connection: DEFAULT_CONNECTION }
 
+/** Property names accepted as connection-level settings. */
 export type ConnectionKeys = keyof Omit<AuthConfiguration, 'connections' | 'connectionsMap'>
+/** Property names accepted in a connection-map entry. */
 export type ConnectionMapKeys = keyof ConnectionMapItem
 
+/**
+ * Applies authority, issuer, alias, and connection-map defaults to a configuration.
+ *
+ * @param config - Authentication configuration to normalize.
+ * @returns A normalized copy of the configuration.
+ */
 export function applyDefaultSettings (config: AuthConfiguration) {
   const settings = { ...config }
   settings.authorityEndpoint ??= settings.authority ?? AUTHORITY_DEFAULT
@@ -106,6 +118,13 @@ function trimTrailingSlashes (value: string): string {
   return end === value.length ? value : value.slice(0, end)
 }
 
+/**
+ * Builds the default trusted issuer list for a tenant and authority.
+ *
+ * @param tenantId - Microsoft Entra tenant ID.
+ * @param authority - Authority URL used to determine the cloud and effective tenant.
+ * @returns Trusted Bot Framework and Microsoft Entra issuer URLs.
+ */
 export function getDefaultIssuers (tenantId: string, authority: string) : string[] {
   // Convert empty string to undefined so resolveAuthority applies its 'botframework.com' default
   const t = getEffectiveTenant(tenantId || undefined, authority)
@@ -268,14 +287,23 @@ export interface AuthConfiguration extends ConnectionSettings {
  * Supported authentication types for agent connections.
  */
 export enum AuthType {
+  /** Client authentication using an X.509 certificate. */
   Certificate = 'Certificate',
+  /** Client authentication using a certificate subject name. */
   CertificateSubjectName = 'CertificateSubjectName',
+  /** Client authentication using a client secret. */
   ClientSecret = 'ClientSecret',
+  /** Authentication using a user-assigned managed identity. */
   UserManagedIdentity = 'UserManagedIdentity',
+  /** Authentication using a system-assigned managed identity. */
   SystemManagedIdentity = 'SystemManagedIdentity',
+  /** Authentication using federated identity credentials. */
   FederatedCredentials = 'FederatedCredentials',
+  /** Authentication using a workload identity token. */
   WorkloadIdentity = 'WorkloadIdentity',
+  /** Authentication through Identity Proxy Manager. */
   IdentityProxyManager = 'IdentityProxyManager',
+  /** Authentication through the Microsoft Entra authentication sidecar. */
   EntraAuthSideCar = 'EntraAuthSideCar'
 }
 

package/src/auth/sidecar/sidecarAuthProvider.ts

@@ -134,6 +134,10 @@ export class SidecarAuthProvider implements AuthProvider {
    * On-behalf-of token exchange — not supported by the sidecar provider in Phase 1.
    */
   async acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+
+  /**
+   * On-behalf-of token exchange with explicit authentication settings — not supported by the sidecar provider in Phase 1.
+   */
   async acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
   async acquireTokenOnBehalfOf (
     _authConfigOrScopes: AuthConfiguration | string[],

package/src/auth/sidecar/sidecarHttpClient.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { isIP } from 'node:net'
 import { debug } from '@microsoft/agents-telemetry'
 import { ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../../errorHelper'
+import { isPrivateOrLoopbackAddress } from '../../utils/ipAddress'
 import {
   DEFAULT_REQUEST_TIMEOUT_MS,
   DEFAULT_RETRY_COUNT,
@@ -139,68 +139,8 @@ export class SidecarHttpClient {
   }
 
   private static isLoopbackOrPrivateHost (host: string): boolean {
-    // URL.hostname wraps IPv6 literals in brackets (e.g. "[::1]"); strip them before classification.
-    const normalized = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host
-    const ipVersion = isIP(normalized)
-    if (ipVersion === 0) {
-      // DNS host: only "localhost" (and subdomains) is treated as safe.
-      const lower = normalized.toLowerCase()
-      return lower === 'localhost' || lower.endsWith('.localhost')
-    }
-    if (ipVersion === 4) {
-      return SidecarHttpClient.isPrivateOrLoopbackIPv4(normalized)
-    }
-    return SidecarHttpClient.isPrivateOrLoopbackIPv6(normalized)
-  }
-
-  private static isPrivateOrLoopbackIPv4 (host: string): boolean {
-    const b = host.split('.').map((p) => parseInt(p, 10))
-    if (b.length !== 4 || b.some((n) => Number.isNaN(n) || n < 0 || n > 255)) {
-      return false
-    }
-    if (b[0] === 127) return true // 127.0.0.0/8 loopback
-    if (b[0] === 10) return true // 10.0.0.0/8
-    if (b[0] === 172 && b[1] >= 16 && b[1] <= 31) return true // 172.16.0.0/12
-    if (b[0] === 192 && b[1] === 168) return true // 192.168.0.0/16
-    if (b[0] === 169 && b[1] === 254) return true // 169.254.0.0/16 link-local
-    return false
-  }
-
-  private static isPrivateOrLoopbackIPv6 (host: string): boolean {
     const lower = host.toLowerCase()
-    if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') return true // loopback (`::` is the unspecified address, not loopback)
-    // IPv4-mapped/-translated addresses in either dotted (::ffff:127.0.0.1)
-    // or hex-compressed (::ffff:7f00:1) form.
-    const mappedIPv4 = SidecarHttpClient.extractMappedIPv4(lower)
-    if (mappedIPv4) {
-      return SidecarHttpClient.isPrivateOrLoopbackIPv4(mappedIPv4)
-    }
-    const firstHextet = parseInt(lower.split(':')[0], 16)
-    if (!Number.isNaN(firstHextet)) {
-      if ((firstHextet & 0xfe00) === 0xfc00) return true // fc00::/7 unique local
-      if ((firstHextet & 0xffc0) === 0xfe80) return true // fe80::/10 link-local
-      if ((firstHextet & 0xffc0) === 0xfec0) return true // fec0::/10 site-local (deprecated)
-    }
-    return false
-  }
-
-  /**
-   * Extracts the embedded IPv4 address from an IPv4-mapped/-translated IPv6 literal, returning it
-   * in dotted-quad form, or `undefined` if `host` is not such an address. Handles both the dotted
-   * form (`::ffff:127.0.0.1`) and the hex-compressed form Node emits (`::ffff:7f00:1`).
-   */
-  private static extractMappedIPv4 (host: string): string | undefined {
-    const dotted = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/)
-    if (dotted) {
-      return dotted[1]
-    }
-    const hex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
-    if (hex) {
-      const high = parseInt(hex[1], 16)
-      const low = parseInt(hex[2], 16)
-      return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`
-    }
-    return undefined
+    return lower === 'localhost' || lower.endsWith('.localhost') || isPrivateOrLoopbackAddress(host)
   }
 
   /**

package/src/cards/taskModuleAction.ts

@@ -9,6 +9,12 @@ import { CardAction } from '@microsoft/agents-activity'
  * Represents a task module action.
  */
 export class TaskModuleAction implements CardAction {
+  /**
+   * Creates an action that invokes a `task/fetch` task module.
+   *
+   * @param title The action title.
+   * @param value The action data as an object or JSON string.
+   */
   constructor (title: string, value: any) {
     this.type = 'invoke'
     this.title = title

package/src/cloudAdapter.ts

@@ -152,7 +152,9 @@ function sanitizeForLog (value: string, max = 256): string {
 function truncateActivityForLog (activity: unknown, max = 1024): string {
   try {
     const json = JSON.stringify(activity)
-    if (!json) return '<unserializable>'
+    if (!json) {
+      return '<unserializable>'
+    }
     // Strip C0/DEL/C1 controls + U+2028/U+2029 from the serialized form so
     // attacker-controlled fields (e.g. activity.text) can't forge log lines.
     // eslint-disable-next-line no-control-regex
@@ -651,18 +653,30 @@ 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 (!this.isOutboundServiceUrlAllowed(activity.serviceUrl)) {
+      return false
+    }
 
-    if (!identity) return true
-    if (!activity.serviceUrl) return true
+    if (!identity) {
+      return true
+    }
+    if (!activity.serviceUrl) {
+      return true
+    }
 
     const claimValue = identity.serviceurl
-    if (typeof claimValue !== 'string') return true
+    if (typeof claimValue !== 'string') {
+      return true
+    }
 
     let claimHost: string | undefined
     let activityHost: string | undefined
-    try { claimHost = new URL(claimValue).hostname.toLowerCase() } catch { /* invalid */ }
-    try { activityHost = new URL(activity.serviceUrl).hostname.toLowerCase() } catch { /* invalid */ }
+    try {
+      claimHost = new URL(claimValue).hostname.toLowerCase()
+    } catch { /* invalid */ }
+    try {
+      activityHost = new URL(activity.serviceUrl).hostname.toLowerCase()
+    } catch { /* invalid */ }
 
     if (claimHost && activityHost && claimHost === activityHost) {
       return true
@@ -682,7 +696,9 @@ export class CloudAdapter extends BaseAdapter {
    * Applies the shared outbound host policy.
    */
   private isOutboundServiceUrlAllowed (serviceUrl: string | undefined): boolean {
-    if (!this._hostValidator.enabled || !serviceUrl || this._hostValidator.isAllowed(serviceUrl)) return true
+    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
@@ -920,8 +936,12 @@ export class CloudAdapter extends BaseAdapter {
     if (typeof serviceUrl !== 'string' || !serviceUrl) {
       throw ExceptionHelper.generateException(TypeError, Errors.ServiceUrlRequired)
     }
-    if (!conversationParameters) throw ExceptionHelper.generateException(TypeError, Errors.ConversationParametersRequired)
-    if (!logic) throw ExceptionHelper.generateException(TypeError, Errors.LogicParameterRequired)
+    if (!conversationParameters) {
+      throw ExceptionHelper.generateException(TypeError, Errors.ConversationParametersRequired)
+    }
+    if (!logic) {
+      throw ExceptionHelper.generateException(TypeError, Errors.LogicParameterRequired)
+    }
 
     const identity = CloudAdapter.createIdentity(audience)
     const restClient = await this.createConnectorClient(serviceUrl, audience, identity)

package/src/configuration/configuration.ts

@@ -27,6 +27,7 @@ export type CloudAdapterConfigurationPatch = Partial<{
 export type OutboundHostValidatorConfigurationPatch = Partial<{
   enabled: boolean
   includeDefaultMicrosoftHosts: boolean
+  allowPrivateNetworkAddresses: boolean
   hosts: readonly string[]
 }>
 export type AuthorizationHandlerPatch = Record<string, unknown>
@@ -105,6 +106,7 @@ const connectionMapParsers = {
 const outboundHostValidatorParsers = {
   enabled: asBoolean,
   includeDefaultMicrosoftHosts: asBoolean,
+  allowPrivateNetworkAddresses: asBoolean,
   hosts: asList
 } satisfies Record<string, (value: string) => unknown>
 
@@ -489,7 +491,7 @@ function parseValue (
     ? parseDocumentValue(parser, value)
     : typeof value === 'string' ? parser(value) : undefined
   if (parsed === undefined) {
-    if (key === 'validateIssuer') {
+    if (key === 'validateIssuer' || key === 'allowPrivateNetworkAddresses') {
       throw ExceptionHelper.generateException(
         TypeError,
         Errors.InvalidBooleanConfigurationValue,
@@ -598,7 +600,7 @@ export function setConfigurationValue (
     if (parsed.key === 'hosts') {
       ;(target.outboundHostValidator as OutboundHostValidatorConfigurationPatch).hosts = parsed.value as string[]
     } else {
-      ;(target.outboundHostValidator as OutboundHostValidatorConfigurationPatch)[parsed.key as 'enabled' | 'includeDefaultMicrosoftHosts'] = parsed.value as boolean
+      ;(target.outboundHostValidator as OutboundHostValidatorConfigurationPatch)[parsed.key as 'enabled' | 'includeDefaultMicrosoftHosts' | 'allowPrivateNetworkAddresses'] = parsed.value as boolean
     }
     return
   }

package/src/configuration/environmentConfiguration.ts

@@ -256,7 +256,13 @@ function bindOutboundHostValidator (
       emitHierarchySuggestion(sourceName, [parts[0], suggestedProperty].join('__'), true)
     }
   }
-  trySet(layer, `outboundHostValidator.${parts[1]}`, value, sourceName)
+  trySet(
+    layer,
+    `outboundHostValidator.${parts[1]}`,
+    value,
+    sourceName,
+    parts[1].toLowerCase() === 'allowprivatenetworkaddresses'
+  )
 }
 
 function bindAuthorizationHandler (

package/src/connector-client/connectorClient.ts

@@ -53,6 +53,7 @@ export class ConnectorClient {
     this._httpClient = httpClient
   }
 
+  /** Gets the HTTP client used for Connector API requests. */
   public get httpClient (): HttpClient {
     return this._httpClient
   }
@@ -127,6 +128,13 @@ export class ConnectorClient {
     })
   }
 
+  /**
+   * Retrieves a member of a conversation.
+   *
+   * @param userId The member's channel user ID.
+   * @param conversationId The conversation ID.
+   * @returns The member's channel account.
+   */
   public async getConversationMember (userId: string, conversationId: string): Promise<ChannelAccount> {
     return trace(ConnectorClientTraceDefinitions.getConversationMember, async ({ record }) => {
       if (!userId || !conversationId) {

package/src/createCloudAdapter.ts

@@ -15,7 +15,9 @@ import { TurnState } from './app/turnState'
  * Result of creating a CloudAdapter from an agent.
  */
 export interface CloudAdapterResult {
+  /** The adapter to use for processing requests. */
   adapter: CloudAdapter
+  /** The application's outbound header propagation callback, when configured. */
   headerPropagation: HeaderPropagationDefinition | undefined
 }
 

package/src/errorHelper.ts

@@ -3,6 +3,7 @@
 
 import { AgentErrorDefinition } from '@microsoft/agents-activity'
 
+/** Error definitions used by the hosting package. */
 export const Errors: { [key: string]: AgentErrorDefinition } = {
   // ============================================================================
   // TurnContext and Activity Errors (-120000 to -120090)
@@ -295,6 +296,16 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'HttpClient requires baseURL when using a relative URL: {url}'
   },
 
+  AttachmentDownloadRedirectLimit: {
+    code: -120292,
+    description: 'Attachment download exceeded the maximum of 50 redirects.'
+  },
+
+  AttachmentDownloadInvalidRedirect: {
+    code: -120293,
+    description: 'Attachment download returned an invalid redirect URL.'
+  },
+
   // ============================================================================
   // Connection and Authentication Errors (-120300 to -120599)
   // ============================================================================