@microsoft/agents-hosting 1.9.1 → 1.10.0-beta.14.ge6d1defc27

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

package/src/storage/memoryStorage.ts

@@ -33,6 +33,7 @@ interface MemoryStorageState {
 class MemoryStorageInternals {
   private static readonly states = new WeakMap<object, MemoryStorageState>()
 
+  /** The shared values and metadata for this storage instance. */
   readonly state: MemoryStorageState
 
   /**
@@ -47,24 +48,53 @@ class MemoryStorageInternals {
     this.state = state
   }
 
+  /**
+   * Saves a value and updates its version and expiration metadata.
+   *
+   * @param key The storage key.
+   * @param item The value to store.
+   * @param expiresAt The optional expiration time, expressed as Unix time in milliseconds.
+   * @returns The new version.
+   */
   save (key: string, item: unknown, expiresAt?: number): string {
     const version = (this.state.etag++).toString()
     this.state.memory[key] = JSON.stringify(item)
     this.state.versions[key] = version
-    if (expiresAt === undefined) delete this.state.expirations[key]
-    else this.state.expirations[key] = expiresAt
+    if (expiresAt === undefined) {
+      delete this.state.expirations[key]
+    } else {
+      this.state.expirations[key] = expiresAt
+    }
     return version
   }
 
+  /**
+   * Gets the version associated with a stored value.
+   *
+   * @param key The storage key.
+   * @param value The stored value.
+   * @returns The version, when available.
+   */
   getVersion (key: string, value: StoreItem): string | undefined {
     return this.state.versions[key] ?? value.eTag as string | undefined
   }
 
+  /**
+   * 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.state.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.memory[key]
     delete this.state.versions[key]
@@ -81,6 +111,11 @@ class MemoryStorageInternals {
 export class MemoryStorage extends MemoryStorageInternals implements Storage {
   private static instance: MemoryStorage
 
+  /**
+   * Creates a legacy in-memory storage provider.
+   *
+   * @param memory Optional backing store to share with another in-memory storage instance.
+   */
   constructor (memory: { [key: string]: string } = {}) {
     super(memory)
   }
@@ -160,8 +195,11 @@ export class MemoryStorage extends MemoryStorageInternals implements Storage {
     })
   }
 
+  /** Returns the process-wide legacy memory storage instance. */
   static getSingleInstance (): MemoryStorage {
-    if (!MemoryStorage.instance) MemoryStorage.instance = new MemoryStorage()
+    if (!MemoryStorage.instance) {
+      MemoryStorage.instance = new MemoryStorage()
+    }
     return MemoryStorage.instance
   }
 }
@@ -323,8 +361,11 @@ export class MemoryStorageV2 extends StorageV2 {
     })
   }
 
+  /** Returns the process-wide V2 memory storage instance. */
   static getSingleInstance (): MemoryStorageV2 {
-    if (!MemoryStorageV2.instance) MemoryStorageV2.instance = new MemoryStorageV2()
+    if (!MemoryStorageV2.instance) {
+      MemoryStorageV2.instance = new MemoryStorageV2()
+    }
     return MemoryStorageV2.instance
   }
 }

package/src/storage/storage.ts

@@ -111,9 +111,13 @@ export interface Storage {
  * available when `status` is {@link StorageOperationStatus.Succeeded}.
  */
 export interface StorageReadResult<T extends object = Record<string, unknown>> {
+  /** The requested storage key. */
   key: string;
+  /** The outcome of the read. */
   status: StorageOperationStatus;
+  /** The stored value when the read succeeds. */
   value?: T;
+  /** The stored version when available. */
   version?: string;
 }
 
@@ -121,8 +125,11 @@ export interface StorageReadResult<T extends object = Record<string, unknown>> {
  * The result of a version 2 storage write operation.
  */
 export interface StorageWriteResult {
+  /** The supplied storage key. */
   key: string;
+  /** The outcome of the write. */
   status: StorageOperationStatus;
+  /** The resulting or current storage version when available. */
   version?: string;
 }
 
@@ -130,8 +137,11 @@ export interface StorageWriteResult {
  * The result of a version 2 storage delete operation.
  */
 export interface StorageDeleteResult {
+  /** The supplied storage key. */
   key: string;
+  /** The outcome of the delete. */
   status: StorageOperationStatus;
+  /** The deleted or current storage version when available. */
   version?: string;
 }
 
@@ -146,16 +156,23 @@ export type StorageDeleteResults = Record<string, StorageDeleteResult>
 
 /** The outcome of one version 2 storage operation. */
 export enum StorageOperationStatus {
+  /** The operation completed successfully. */
   Succeeded = 'succeeded',
+  /** No item exists for the key. */
   NotFound = 'notFound',
+  /** A create-only operation found an existing item. */
   Conflict = 'conflict',
+  /** The expected version did not match the current version. */
   ConditionNotMet = 'conditionNotMet',
 }
 
 /** The write mode for a version 2 storage operation. */
 export enum StorageWriteMode {
+  /** Creates a new item or replaces an existing item. */
   Upsert = 'upsert',
+  /** Creates an item only when the key does not exist. */
   CreateOnly = 'createOnly',
+  /** Replaces an item only when the key exists. */
   Replace = 'replace',
 }
 
@@ -168,12 +185,15 @@ export interface StorageWriteOptions {
    * duration has elapsed. Values must be finite numbers greater than zero.
    */
   ttl?: number;
+  /** The condition controlling whether existing items may be written. */
   mode?: StorageWriteMode;
+  /** The storage version that must match before writing. */
   expectedVersion?: string;
 }
 
 /** Options applied to every item in a version 2 delete operation. */
 export interface StorageDeleteOptions {
+  /** The storage version that must match before deleting. */
   expectedVersion?: string;
 }
 

package/src/storage/storageCompatibility.ts

@@ -31,8 +31,12 @@ export function asStorageV2 (storage: StorageProvider): StorageV2 {
 /** Returns a successful V2 read value, maps not-found to undefined, and rejects invalid results. */
 export function getStorageReadValue<T extends object> (results: StorageReadResults<T> | null | undefined, key: string): T | undefined {
   const result = results?.[key]
-  if (result?.status === StorageOperationStatus.NotFound) return undefined
-  if (result?.status === StorageOperationStatus.Succeeded) return result.value
+  if (result?.status === StorageOperationStatus.NotFound) {
+    return undefined
+  }
+  if (result?.status === StorageOperationStatus.Succeeded) {
+    return result.value
+  }
   throwStorageResultError('read', key, result?.status)
 }
 
@@ -44,7 +48,9 @@ class StorageToStorageV2Adapter extends StorageV2 {
 
   async read<T extends object = Record<string, unknown>> (keys: string[]): Promise<StorageReadResults<T>> {
     validateKeys(keys)
-    if (keys.length === 0) return {}
+    if (keys.length === 0) {
+      return {}
+    }
 
     const items = await this.storage.read(keys)
     return Object.fromEntries(keys.map(key => {
@@ -64,7 +70,9 @@ class StorageToStorageV2Adapter extends StorageV2 {
       throwUnsupportedOption('ttl')
     }
     validateExpectedVersion(options?.expectedVersion)
-    if (Object.keys(changes).length === 0) return {}
+    if (Object.keys(changes).length === 0) {
+      return {}
+    }
     const legacyChanges = Object.fromEntries(Object.entries(changes).map(([key, value]) => [
       key,
       options?.expectedVersion === undefined
@@ -81,7 +89,9 @@ class StorageToStorageV2Adapter extends StorageV2 {
     if (options?.expectedVersion !== undefined) {
       throwUnsupportedOption('expectedVersion')
     }
-    if (keys.length === 0) return {}
+    if (keys.length === 0) {
+      return {}
+    }
 
     await this.storage.delete(keys)
     return Object.fromEntries(keys.map(key => [key, { key, status: StorageOperationStatus.Succeeded }]))
@@ -116,7 +126,9 @@ function validateChanges (changes: Record<string, unknown>): void {
 }
 
 function removeLegacyETag<T> (value: T): T {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) return value
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return value
+  }
   const { eTag: _eTag, ...withoutETag } = value as Record<string, unknown>
   return withoutETag as T
 }

package/src/storage/storageExpiry.ts

@@ -7,6 +7,13 @@ import { StorageWriteOptions } from './storage'
 import { ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../errorHelper'
 
+/**
+ * Computes an absolute expiration time for a storage write.
+ *
+ * @param options The write options containing an optional TTL in seconds.
+ * @returns The expiration time in milliseconds since the Unix epoch, or `undefined` when no TTL is set.
+ * @throws A `RangeError` when the TTL is not finite or is not greater than zero.
+ */
 export function getStorageWriteExpiry (options?: StorageWriteOptions): number | undefined {
   const ttl = options?.ttl
   if (ttl === undefined) {

package/src/turnContext.ts

@@ -82,9 +82,16 @@ export class TurnContext {
    *
    * @param adapterOrContext The adapter that created this context, or another TurnContext to clone
    * @param request The activity for the turn (required when first parameter is an adapter)
+   * @param identity The authenticated identity for the turn.
    */
   constructor (adapterOrContext: BaseAdapter, request: Activity, identity?: JwtPayload)
+  /**
+   * Creates a context by copying another turn context.
+   *
+   * @param adapterOrContext The turn context to copy.
+   */
   constructor (adapterOrContext: TurnContext)
+  /** Implements the adapter and copy constructor overloads. */
   constructor (adapterOrContext: BaseAdapter | TurnContext, request?: Activity, identity?: JwtPayload) {
     if (adapterOrContext instanceof TurnContext) {
       adapterOrContext.copyTo(this)
@@ -367,6 +374,7 @@ export class TurnContext {
     return this._activity as Activity
   }
 
+  /** Gets the authenticated identity for the turn. */
   get identity (): JwtPayload {
     return this._identity as JwtPayload
   }
@@ -382,6 +390,7 @@ export class TurnContext {
     return this._respondedRef.responded
   }
 
+  /** Marks the turn as having sent a response. */
   set responded (value: boolean) {
     if (!value) {
       throw ExceptionHelper.generateException(Error, Errors.CannotSetRespondedToFalse)
@@ -404,6 +413,7 @@ export class TurnContext {
     return undefined
   }
 
+  /** Sets the locale stored in the turn state. */
   set locale (value: string | undefined) {
     let turnObj = this._turnState.get(this._turn)
     if (turnObj) {
@@ -426,6 +436,7 @@ export class TurnContext {
     return this._turnState
   }
 
+  /** Gets the streaming response associated with this context. */
   get streamingResponse (): StreamingResponse {
     return this._streamingResponse
   }