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

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
   }

package/src/utils/env.ts

@@ -87,11 +87,19 @@ export const envParserUtils = {
  *   unrecognized.
  */
 export function parseBooleanEnv (value: string | undefined): boolean | undefined {
-  if (value === undefined) return undefined
+  if (value === undefined) {
+    return undefined
+  }
   const v = value.trim().toLowerCase()
-  if (v === 'true' || v === '1') return true
-  if (v === '') return undefined
-  if (v === 'false' || v === '0') return false
+  if (v === 'true' || v === '1') {
+    return true
+  }
+  if (v === '') {
+    return undefined
+  }
+  if (v === 'false' || v === '0') {
+    return false
+  }
   return undefined
 }
 
@@ -104,7 +112,9 @@ export function parseBooleanEnv (value: string | undefined): boolean | undefined
  * @returns A finite integer, or `fallback` when the input cannot be parsed.
  */
 export function parseIntEnv (value: string | undefined, fallback: number): number {
-  if (value === undefined || value.trim() === '') return fallback
+  if (value === undefined || value.trim() === '') {
+    return fallback
+  }
   const parsed = parseInt(value, 10)
   return Number.isNaN(parsed) ? fallback : parsed
 }
@@ -132,7 +142,9 @@ export function suggestClosest (
   candidates: readonly string[],
   maxDistance = 2
 ): string | undefined {
-  if (!input) return undefined
+  if (!input) {
+    return undefined
+  }
   const a = input.toLowerCase()
   const cutoff = Math.min(maxDistance, Math.max(1, Math.ceil(a.length / 2)))
   let best: { name: string, distance: number } | undefined
@@ -140,7 +152,9 @@ export function suggestClosest (
     const d = levenshtein(a, candidate.toLowerCase())
     if (d <= cutoff && (!best || d < best.distance)) {
       best = { name: candidate, distance: d }
-      if (d === 0) break
+      if (d === 0) {
+        break
+      }
     }
   }
   return best?.name
@@ -148,11 +162,19 @@ export function suggestClosest (
 
 /** Standard Levenshtein edit distance using a single-row dynamic-programming table. */
 function levenshtein (a: string, b: string): number {
-  if (a === b) return 0
-  if (a.length === 0) return b.length
-  if (b.length === 0) return a.length
+  if (a === b) {
+    return 0
+  }
+  if (a.length === 0) {
+    return b.length
+  }
+  if (b.length === 0) {
+    return a.length
+  }
   const row = new Array<number>(b.length + 1)
-  for (let j = 0; j <= b.length; j++) row[j] = j
+  for (let j = 0; j <= b.length; j++) {
+    row[j] = j
+  }
   for (let i = 1; i <= a.length; i++) {
     let prev = i - 1
     row[0] = i

package/src/utils/ipAddress.ts

@@ -0,0 +1,63 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { isIP } from 'node:net'
+
+function normalizeAddress (address: string): string | undefined {
+  const unwrapped = address.startsWith('[') && address.endsWith(']') ? address.slice(1, -1) : address
+  const version = isIP(unwrapped)
+  if (version === 0) {
+    return undefined
+  }
+  return version === 6 ? new URL(`http://[${unwrapped}]`).hostname.slice(1, -1) : unwrapped
+}
+
+function mappedIPv4 (address: string): string | undefined {
+  const match = address.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
+  if (!match) {
+    return undefined
+  }
+  const high = parseInt(match[1], 16)
+  const low = parseInt(match[2], 16)
+  return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`
+}
+
+export function isPrivateOrLoopbackAddress (address: string): boolean {
+  const normalized = normalizeAddress(address)
+  if (!normalized) {
+    return false
+  }
+  const ipv4 = mappedIPv4(normalized) ?? normalized
+  if (isIP(ipv4) === 4) {
+    const bytes = ipv4.split('.').map(Number)
+    return bytes[0] === 127 ||
+      bytes[0] === 10 ||
+      (bytes[0] === 172 && bytes[1] >= 16 && bytes[1] <= 31) ||
+      (bytes[0] === 192 && bytes[1] === 168) ||
+      (bytes[0] === 169 && bytes[1] === 254)
+  }
+
+  if (normalized === '::1') {
+    return true
+  }
+  const firstHextet = parseInt(normalized.split(':')[0], 16)
+  return (firstHextet & 0xfe00) === 0xfc00 ||
+    (firstHextet & 0xffc0) === 0xfe80 ||
+    (firstHextet & 0xffc0) === 0xfec0
+}
+
+export function isBlockedOutboundAddress (address: string): boolean {
+  const normalized = normalizeAddress(address)
+  if (!normalized) {
+    return true
+  }
+  const ipv4 = mappedIPv4(normalized) ?? normalized
+  const [first, second] = ipv4.split('.').map(Number)
+  // RFC 6598 shared space is outbound-only; it must not become trusted sidecar space.
+  return normalized === '::' ||
+    ipv4 === '0.0.0.0' ||
+    (first === 100 && second >= 64 && second <= 127) ||
+    isPrivateOrLoopbackAddress(normalized)
+}

package/src/utils/outboundUrl.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { promises as dns } from 'node:dns'
+import { isIP } from 'node:net'
+import { debug } from '@microsoft/agents-telemetry'
+import { isBlockedOutboundAddress } from './ipAddress'
+
+const logger = debug('agents:outboundHostValidator')
+
+export function getHttpsUrl (input: string | URL | null | undefined): URL | undefined {
+  if (!input) {
+    return undefined
+  }
+  try {
+    const url = input instanceof URL ? input : new URL(input)
+    return url.protocol === 'https:' && !url.username && !url.password ? url : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function isLocalOrBlockedHost (host: string): boolean {
+  const unwrapped = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host
+  return host === 'localhost' || host.endsWith('.localhost') ||
+    (isIP(unwrapped) !== 0 && isBlockedOutboundAddress(unwrapped))
+}
+
+export async function hasAllowedOutboundAddresses (url: URL, allowPrivateNetworkAddresses = false): Promise<boolean> {
+  if (allowPrivateNetworkAddresses) {
+    return true
+  }
+  const host = url.hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '')
+  if (isLocalOrBlockedHost(host)) {
+    return false
+  }
+  if (isIP(host) !== 0) {
+    return true
+  }
+
+  try {
+    const addresses = await dns.lookup(host, { all: true })
+    return addresses.length > 0 && addresses.every(({ address }) => !isBlockedOutboundAddress(address))
+  } catch {
+    logger.warn(`Attachment destination DNS lookup failed. Host='${host}'`)
+    return false
+  }
+}

package/src/utils.ts

@@ -18,7 +18,9 @@ export const mergeDefined = <T extends Record<string, any>>(
 ): T => {
   const result: Partial<T> = {}
   for (const layer of layers) {
-    if (layer) Object.assign(result, prune(layer))
+    if (layer) {
+      Object.assign(result, prune(layer))
+    }
   }
   return result as T
 }