@microsoft/agents-hosting 1.10.0-beta.9.g18d68b903e → 1.10.1

package/src/headerPropagation.ts

@@ -17,14 +17,21 @@ export class HeaderPropagation implements HeaderPropagationCollection {
 
   private _protectedHeaders = ['x-ms-correlation-id']
 
+  /** Gets the normalized headers received on the incoming request. */
   public get incoming (): Record<string, string> {
     return this._incomingRequests
   }
 
+  /** Gets the headers selected for propagation to outgoing requests. */
   public get outgoing (): Record<string, string> {
     return this._outgoingHeaders
   }
 
+  /**
+   * Creates a header propagation collection from incoming request headers.
+   *
+   * @param headers The incoming headers, including optional multi-value headers.
+   */
   constructor (headers: Record<string, string | string[] | undefined>) {
     if (!headers) {
       throw ExceptionHelper.generateException(Error, Errors.HeadersRequired)
@@ -39,6 +46,11 @@ export class HeaderPropagation implements HeaderPropagationCollection {
     this._protectedHeaders = protectedHeaders // Restore protected headers list after propagation
   }
 
+  /**
+   * Copies existing incoming header values to the outgoing collection.
+   *
+   * @param headers The header names to propagate.
+   */
   propagate (headers: string[]) {
     this.process(headers.map(h => [h, '']), key => {
       if (this._incomingRequests[key] && !this._outgoingHeaders[key]) {
@@ -47,6 +59,11 @@ export class HeaderPropagation implements HeaderPropagationCollection {
     })
   }
 
+  /**
+   * Adds headers that do not already exist in either collection.
+   *
+   * @param headers The headers to add.
+   */
   add (headers: Record<string, string>) {
     this.process(Object.entries(headers ?? {}), (key, value) => {
       if (!this._incomingRequests[key] && !this._outgoingHeaders[key]) {
@@ -55,6 +72,11 @@ export class HeaderPropagation implements HeaderPropagationCollection {
     })
   }
 
+  /**
+   * Appends values to headers that already exist in either collection.
+   *
+   * @param headers The values to append.
+   */
   concat (headers: Record<string, string>) {
     this.process(Object.entries(headers ?? {}), (key, value) => {
       if (this._incomingRequests[key] || this._outgoingHeaders[key]) {
@@ -63,12 +85,23 @@ export class HeaderPropagation implements HeaderPropagationCollection {
     })
   }
 
+  /**
+   * Sets outgoing header values unless the headers are protected.
+   *
+   * @param headers The headers to set.
+   */
   override (headers: Record<string, string>) {
     this.process(Object.entries(headers ?? {}), (key, value) => {
       this._outgoingHeaders[key] = value
     })
   }
 
+  /**
+   * Finds a known header name without regard to casing.
+   *
+   * @param key The header name to find.
+   * @returns The original-cased header name, or `undefined` when it is unknown.
+   */
   key (key: string) {
     return this._keys.find(k => k.toLowerCase() === key.toLowerCase())
   }
@@ -113,6 +146,11 @@ export class HeaderPropagation implements HeaderPropagationCollection {
  * A function type that defines how headers should be propagated.
  */
 export interface HeaderPropagationDefinition {
+  /**
+   * Configures outgoing headers for a request.
+   *
+   * @param headers The collection to configure.
+   */
   (headers: HeaderPropagationCollection): void
 }
 

package/src/httpClient.ts

@@ -11,13 +11,21 @@ import { Errors } from './errorHelper'
  * Configuration for an HTTP request.
  */
 export interface HttpRequestConfig {
+  /** The HTTP method. */
   method: string
+  /** The absolute URL or path relative to the client's base URL. */
   url: string
+  /** Headers to merge with the client's default headers. */
   headers?: Record<string, string>
+  /** The request body. */
   data?: unknown
+  /** Query parameters to append to the URL. */
   params?: Record<string, string | undefined>
+  /** The format used to read the response body. */
   responseType?: 'json' | 'arraybuffer' | 'stream'
+  /** The request timeout in milliseconds. */
   timeout?: number
+  /** A signal used to cancel the request. */
   signal?: AbortSignal
 }
 
@@ -25,10 +33,15 @@ export interface HttpRequestConfig {
  * Represents an HTTP response.
  */
 export interface HttpResponse<T = unknown> {
+  /** The parsed response body. */
   data: T
+  /** The HTTP status code. */
   status: number
+  /** The HTTP status text. */
   statusText: string
+  /** The response headers. */
   headers: Headers
+  /** The configuration used for the request. */
   config: HttpRequestConfig
 }
 
@@ -36,7 +49,9 @@ export interface HttpResponse<T = unknown> {
  * Options for creating an HttpClient instance.
  */
 export interface HttpClientOptions {
+  /** The base URL used for relative request URLs. */
   baseURL?: string
+  /** Default headers included with every request. */
   headers?: Record<string, string>
 }
 
@@ -47,27 +62,48 @@ export class HttpClient {
   private _baseURL: string
   private _defaultHeaders: Record<string, string>
 
+  /**
+   * Creates an HTTP client.
+   *
+   * @param options The base URL and default headers.
+   */
   constructor (options: HttpClientOptions = {}) {
     this._baseURL = options.baseURL ?? ''
     this._defaultHeaders = this.normalizeHeaders(options.headers)
   }
 
+  /** Gets the base URL used for relative requests. */
   get baseURL (): string {
     return this._baseURL
   }
 
+  /** Gets the normalized default request headers. */
   get defaultHeaders (): Record<string, string> {
     return this._defaultHeaders
   }
 
+  /** Replaces the default request headers. */
   set defaultHeaders (headers: Record<string, string>) {
     this._defaultHeaders = this.normalizeHeaders(headers)
   }
 
+  /**
+   * Sets a default request header.
+   *
+   * @param name The header name.
+   * @param value The header value.
+   */
   setHeader (name: string, value: string): void {
     this._defaultHeaders[name.toLowerCase()] = value
   }
 
+  /**
+   * Sends an HTTP request.
+   *
+   * @param config The request configuration.
+   * @returns The response with its parsed body.
+   * @throws An {@link HttpError} when the response status is not successful.
+   */
   async request<T = unknown> (config: HttpRequestConfig): Promise<HttpResponse<T>> {
     const url = this.buildUrl(config.url, config.params)
     const headers = this.normalizeHeaders({ ...this._defaultHeaders, ...config.headers })
@@ -142,6 +178,13 @@ export class HttpClient {
     return httpResponse
   }
 
+  /**
+   * Sends an HTTP request, defaulting to GET.
+   *
+   * @param url The absolute URL or path relative to the client's base URL.
+   * @param options Additional request options. The `method` and `url` options override the defaults.
+   * @returns The response with its parsed body.
+   */
   async get<T = unknown> (url: string, options?: Partial<HttpRequestConfig>): Promise<HttpResponse<T>> {
     return this.request<T>({ method: 'get', url, ...options })
   }
@@ -192,10 +235,20 @@ export class HttpClient {
  * Error thrown when an HTTP request fails.
  */
 export class HttpError extends Error {
+  /** The unsuccessful HTTP response. */
   public readonly response: HttpResponse
+  /** The configuration used for the request. */
   public readonly config: HttpRequestConfig
+  /** The HTTP status code. */
   public readonly status: number
 
+  /**
+   * Creates an HTTP request error.
+   *
+   * @param message The error message.
+   * @param response The unsuccessful response.
+   * @param config The request configuration.
+   */
   constructor (message: string, response: HttpResponse, config: HttpRequestConfig) {
     super(message)
     this.name = 'HttpError'
@@ -204,6 +257,11 @@ export class HttpError extends Error {
     this.status = response.status
   }
 
+  /**
+   * Returns a serializable representation of the error.
+   *
+   * @returns The error, request, and response details.
+   */
   toJSON (): Record<string, unknown> {
     return {
       message: this.message,

package/src/interfaces/webResponse.ts

@@ -17,11 +17,17 @@
  * longer needs to import types from `express` at compile time.
  */
 export interface WebResponse {
+  /** Sets the HTTP status code. */
   status (code: number): this
+  /** Sets a response header. */
   setHeader (name: string, value: string): this
+  /** Sends an optional response body. */
   send (body?: unknown): this
+  /** Ends the response. */
   end (): this
+  /** Indicates whether response headers have been sent. */
   headersSent: boolean
+  /** Indicates whether the response stream has ended. */
   writableEnded: boolean
 }
 
@@ -40,5 +46,6 @@ export type NextFunction = (err?: any) => void
  * (`req.params.conversationId`) without coupling to Express's `Request` type.
  */
 export interface WebRequestParamsCarrier {
+  /** Route parameters parsed from the request URL. */
   params?: Record<string, string | undefined>
 }

package/src/middlewareSet.ts

@@ -10,6 +10,12 @@ const logger = debug('agents:middleware')
  * Interface for middleware.
  */
 export interface Middleware {
+  /**
+   * Processes a turn and optionally continues the middleware chain.
+   *
+   * @param context The current turn context.
+   * @param next The callback that continues the middleware chain.
+   */
   onTurn: (context: TurnContext, next: () => Promise<void>) => Promise<void>
 }
 

package/src/oauth/userTokenClient.ts

@@ -34,6 +34,7 @@ function formatHttpErrorMessage (error: HttpError): string {
  * Client for managing user tokens.
  */
 export class UserTokenClient {
+  /** The HTTP client used for token service requests. */
   client: HttpClient
   private msAppId: string = ''
   private authProvider?: AuthProvider
@@ -58,6 +59,13 @@ export class UserTokenClient {
    */
   constructor (httpClient: HttpClient, authProvider?: AuthProvider, authScope?: string)
 
+  /**
+   * Initializes the client from an application ID or an HTTP client.
+   *
+   * @param param The application ID or configured HTTP client.
+   * @param authProvider The optional provider used to acquire an access token lazily.
+   * @param authScope The optional access-token scope.
+   */
   constructor (param: string | HttpClient, authProvider?: AuthProvider, authScope?: string) {
     if (typeof param === 'string') {
       const baseURL = getTokenServiceEndpoint()
@@ -260,6 +268,11 @@ export class UserTokenClient {
     })
   }
 
+  /**
+   * Replaces the bearer token used for token service requests.
+   *
+   * @param token The access token.
+   */
   public updateAuthToken (token: string): void {
     this.client.setHeader('Authorization', `Bearer ${token}`)
     this.authInitialized = true

package/src/outboundHostValidator.ts

@@ -9,6 +9,7 @@ import {
 } from './configuration/configuration'
 import { loadModernEnvironmentConfiguration } from './configuration/environmentConfiguration'
 import { mergeDefined } from './utils'
+import { getHttpsUrl, hasAllowedOutboundAddresses, isLocalOrBlockedHost } from './utils/outboundUrl'
 
 /** Hosts used by Microsoft channel callbacks and hosted attachments. */
 const DEFAULT_MICROSOFT_HOSTS = Object.freeze([
@@ -37,6 +38,12 @@ export interface OutboundHostValidatorOptions {
    */
   includeDefaultMicrosoftHosts?: boolean
 
+  /**
+   * Allows allowlisted HTTPS destinations to use private, shared (RFC 6598),
+   * loopback, link-local, or unspecified addresses. Defaults to `false`.
+   */
+  allowPrivateNetworkAddresses?: 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.
@@ -46,7 +53,14 @@ export interface OutboundHostValidatorOptions {
 
 /** A policy that decides whether an outbound URL is safe to request. */
 export interface OutboundUrlPolicy {
+  /** Indicates whether URL validation is enforced. */
   readonly enabled: boolean
+  /**
+   * Determines whether an outbound URL is allowed.
+   *
+   * @param url The URL to validate.
+   * @returns `true` when the URL is allowed.
+   */
   isAllowed(url: string | URL | null | undefined): boolean
 }
 
@@ -54,43 +68,88 @@ export interface OutboundUrlPolicy {
  * 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.
+ * policy is disabled by default to preserve existing SDK behavior. Enabled
+ * policies require HTTPS without userinfo and restrict private addresses.
+ * Attachment downloaders additionally validate DNS answers and redirect hops.
  */
 export class OutboundHostValidator implements OutboundUrlPolicy {
+  /** Indicates whether allowlist enforcement is enabled. */
   public readonly enabled: boolean
   private readonly suffixes: ReadonlySet<string>
+  private readonly allowPrivateNetworkAddresses: boolean
 
+  /**
+   * Creates an outbound host validator.
+   *
+   * @param options The allowlist configuration.
+   */
   public constructor (options: OutboundHostValidatorOptions = {}) {
     const resolved = options.configurationContext
       ? resolveOutboundHostValidatorOptions(options)
       : options
     this.enabled = resolved.enabled ?? false
+    this.allowPrivateNetworkAddresses = resolved.allowPrivateNetworkAddresses ?? false
 
     const suffixes = new Set<string>()
     if (resolved.includeDefaultMicrosoftHosts ?? true) {
-      for (const host of DEFAULT_MICROSOFT_HOSTS) suffixes.add(host)
+      for (const host of DEFAULT_MICROSOFT_HOSTS) {
+        suffixes.add(host)
+      }
     }
 
     for (const host of resolved.hosts ?? []) {
       const normalized = normalizeConfiguredHost(host)
-      if (normalized) suffixes.add(normalized)
+      if (normalized) {
+        suffixes.add(normalized)
+      }
     }
 
     this.suffixes = suffixes
   }
 
+  /**
+   * Determines whether a URL's host matches the configured allowlist.
+   *
+   * @param input The absolute URL to validate.
+   * @returns `true` when validation is disabled or the host is allowed.
+   */
   public isAllowed (input: string | URL | null | undefined): boolean {
-    if (!this.enabled) return true
+    if (!this.enabled) {
+      return true
+    }
 
-    const host = getUrlHost(input)
-    if (!host) return false
+    const url = getHttpsUrl(input)
+    if (!url) {
+      return false
+    }
+    const host = normalizeHostname(url.hostname)
+    if (!host || (!this.allowPrivateNetworkAddresses && isLocalOrBlockedHost(host))) {
+      return false
+    }
 
     for (const suffix of this.suffixes) {
-      if (host === suffix || host.endsWith(`.${suffix}`)) return true
+      if (host === suffix || host.endsWith(`.${suffix}`)) {
+        return true
+      }
     }
 
     return false
   }
+
+  /**
+   * Checks the host policy and all resolved destination addresses before an attachment request.
+   * DNS prevalidation does not pin the HTTP connection to the checked addresses.
+   */
+  public async isAllowedAsync (input: string | URL | null | undefined): Promise<boolean> {
+    if (!this.isAllowed(input)) {
+      return false
+    }
+    if (!this.enabled) {
+      return true
+    }
+    const url = getHttpsUrl(input)
+    return url !== undefined && await hasAllowedOutboundAddresses(url, this.allowPrivateNetworkAddresses)
+  }
 }
 
 /**
@@ -115,11 +174,18 @@ function resolveOutboundHostValidatorOptions (
   const external = getConfigurationSnapshot(options.configurationContext)
   const fromEnv = loadOutboundHostValidatorOptionsFromEnv()
   const direct: OutboundHostValidatorOptions = {}
-  if (options.enabled !== undefined) direct.enabled = options.enabled
+  if (options.enabled !== undefined) {
+    direct.enabled = options.enabled
+  }
   if (options.includeDefaultMicrosoftHosts !== undefined) {
     direct.includeDefaultMicrosoftHosts = options.includeDefaultMicrosoftHosts
   }
-  if (options.hosts !== undefined) direct.hosts = options.hosts
+  if (options.hosts !== undefined) {
+    direct.hosts = options.hosts
+  }
+  if (options.allowPrivateNetworkAddresses !== undefined) {
+    direct.allowPrivateNetworkAddresses = options.allowPrivateNetworkAddresses
+  }
   return mergeDefined<OutboundHostValidatorOptions>(
     external.fallback.outboundHostValidator,
     fromEnv,
@@ -129,25 +195,20 @@ function resolveOutboundHostValidatorOptions (
   )
 }
 
-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)
+  if (!candidate) {
+    return undefined
+  }
+  if (candidate.startsWith('*.')) {
+    candidate = candidate.slice(2)
+  }
 
   try {
     const absolute = new URL(candidate)
-    if (absolute.hostname) return normalizeHostname(absolute.hostname)
+    if (absolute.hostname) {
+      return normalizeHostname(absolute.hostname)
+    }
   } catch {
     // A bare host, host:port, or host/path is handled below.
   }

package/src/storage/fileStorage.ts

@@ -30,16 +30,29 @@ class FileStorageInternals {
   private readonly statePath: string
   private readonly versionsPath: string
   private readonly expirationsPath: string
+
+  /** The stored values keyed by storage key. */
   readonly state: Record<string, unknown>
+
+  /** The current version associated with each storage key. */
   readonly versions: Record<string, string>
+
+  /** The expiration time associated with each storage key, expressed as Unix time in milliseconds. */
   readonly expirations: Record<string, number>
 
+  /**
+   * Creates the shared file storage implementation.
+   *
+   * @param folder The folder containing the storage files.
+   */
   constructor (folder: string) {
     fs.mkdirSync(folder, { recursive: true })
     this.statePath = path.join(folder, 'state.json')
     this.versionsPath = path.join(folder, 'state.versions.json')
     this.expirationsPath = path.join(folder, 'state.expirations.json')
-    if (!fs.existsSync(this.statePath)) fs.writeFileSync(this.statePath, '{}')
+    if (!fs.existsSync(this.statePath)) {
+      fs.writeFileSync(this.statePath, '{}')
+    }
     this.state = JSON.parse(fs.readFileSync(this.statePath, 'utf8')) as Record<string, unknown>
     this.versions = fs.existsSync(this.versionsPath)
       ? JSON.parse(fs.readFileSync(this.versionsPath, 'utf8')) as Record<string, string>
@@ -49,6 +62,7 @@ class FileStorageInternals {
       : {}
   }
 
+  /** Writes the current storage state and metadata to disk. */
   flush (): void {
     fs.writeFileSync(this.statePath, JSON.stringify(this.state, null, 2))
     if (fs.existsSync(this.versionsPath) || Object.keys(this.versions).length > 0) {
@@ -59,17 +73,34 @@ class FileStorageInternals {
     }
   }
 
+  /**
+   * Gets the current version for a key, creating one when necessary.
+   *
+   * @param key The storage key.
+   * @returns The current version.
+   */
   getOrCreateVersion (key: string): string {
     const version = this.versions[key] ?? randomUUID()
     this.versions[key] = version
     return version
   }
 
+  /**
+   * Determines whether a stored value has expired.
+   *
+   * @param key The storage key.
+   * @returns `true` when the value has expired; otherwise, `false`.
+   */
   isExpired (key: string): boolean {
     const expiresAt = this.expirations[key]
     return expiresAt !== undefined && expiresAt <= Date.now()
   }
 
+  /**
+   * Removes a value and its version and expiration metadata.
+   *
+   * @param key The storage key.
+   */
   remove (key: string): void {
     delete this.state[key]
     delete this.versions[key]
@@ -232,7 +263,9 @@ export class FileStorageV2 extends StorageV2 {
           version: version ?? this.internals.getOrCreateVersion(key),
         }]
       }))
-      if (createdVersion) this.internals.flush()
+      if (createdVersion) {
+        this.internals.flush()
+      }
       return results
     })
   }
@@ -277,13 +310,18 @@ export class FileStorageV2 extends StorageV2 {
           const version = randomUUID()
           this.internals.state[key] = structuredClone(value)
           this.internals.versions[key] = version
-          if (expiresAt === undefined) delete this.internals.expirations[key]
-          else this.internals.expirations[key] = expiresAt
+          if (expiresAt === undefined) {
+            delete this.internals.expirations[key]
+          } else {
+            this.internals.expirations[key] = expiresAt
+          }
           results[key] = { key, status: StorageOperationStatus.Succeeded, version }
           changed = true
         }
       }
-      if (changed || createdVersion) this.internals.flush()
+      if (changed || createdVersion) {
+        this.internals.flush()
+      }
       return results
     })
   }
@@ -325,7 +363,9 @@ export class FileStorageV2 extends StorageV2 {
           changed = true
         }
       }
-      if (changed || createdVersion) this.internals.flush()
+      if (changed || createdVersion) {
+        this.internals.flush()
+      }
       return results
     })
   }