@microsoft/agents-hosting 1.8.1 → 1.9.0-beta.18.g6b8111bba5

package/src/errorHelper.ts

@@ -432,6 +432,14 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'MSAL HTTP request failed: {message}'
   },
 
+  /**
+   * Error thrown when a delegated token credential's provider returns a response without a usable token.
+   */
+  NullTokenResponse: {
+    code: -120393,
+    description: 'The token response provider returned a null response or a response without a token.'
+  },
+
   /**
    * Error thrown when an MSAL HTTP response body cannot be parsed as JSON.
    */
@@ -440,6 +448,14 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'MSAL returned an unparsable response body'
   },
 
+  /**
+   * Error thrown when a security-sensitive boolean configuration value is invalid.
+   */
+  InvalidBooleanConfigurationValue: {
+    code: -120394,
+    description: 'Configuration source "{sourceName}" returned an invalid boolean for "{path}". Expected one of true/false/1/0.'
+  },
+
   FailedToAcquireTokenUsingCertificate: {
     code: -120395,
     description: 'Failed to acquire token using certificate'
@@ -570,11 +586,11 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
   },
 
   /**
-     * Error thrown when authorization option is not available in app options.
+     * Error thrown when no authorization handlers were resolved.
      */
   AuthorizationOptionNotAvailable: {
     code: -120530,
-    description: 'The Application.authorization property is unavailable because no authorization options were configured.'
+    description: 'The Application.authorization property is unavailable because no authorization handlers were resolved.'
   },
 
   /**
@@ -782,6 +798,14 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'Changes are required when writing.'
   },
 
+  /**
+   * Error thrown when a storage TTL value is invalid.
+   */
+  InvalidStorageTtl: {
+    code: -120703,
+    description: 'StorageWriteOptions.ttl must be a finite number greater than zero.'
+  },
+
   /**
      * Error thrown when storage option is not available in app options.
      */
@@ -1035,6 +1059,90 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'The Entra Agent ID sidecar returned an unsupported authorization scheme `{scheme}`. Only the Bearer scheme is supported'
   },
 
+  // ============================================================================
+  // Configuration Source Errors (-120812 to -120827)
+  // ============================================================================
+
+  ConfigurationAlreadyConsumed: {
+    code: -120812,
+    description: 'Configuration sources must be preloaded before the first configuration consumer is created.'
+  },
+
+  ConfigurationSourceNameRequired: {
+    code: -120813,
+    description: 'Configuration source name must be a non-empty string.'
+  },
+
+  DuplicateConfigurationSource: {
+    code: -120814,
+    description: 'Configuration source name `{sourceName}` is registered more than once.'
+  },
+
+  ConfigurationSourceLoadFailed: {
+    code: -120815,
+    description: 'Configuration source `{sourceName}` failed to load.'
+  },
+
+  InvalidConfigurationPath: {
+    code: -120816,
+    description: 'Configuration source `{sourceName}` returned unsupported canonical path `{path}`.'
+  },
+
+  InvalidConfigurationValue: {
+    code: -120817,
+    description: 'Configuration source `{sourceName}` returned an invalid value for canonical path `{path}`.'
+  },
+
+  ConfigurationPreloadInProgress: {
+    code: -120818,
+    description: 'Another configuration preload is already in progress.'
+  },
+
+  InvalidConnectionMapEntry: {
+    code: -120819,
+    description: 'Connection map entry at index {index} must define both serviceUrl and connection.'
+  },
+
+  ConfigurationAlreadyPreloaded: {
+    code: -120820,
+    description: 'Configuration sources have already been preloaded for this process.'
+  },
+
+  UnsupportedRuntimeConfigurationField: {
+    code: -120821,
+    description: 'Configuration source `{sourceName}` returned field `{path}`, which is not supported by the JavaScript SDK.'
+  },
+
+  InvalidConfigurationSourceResult: {
+    code: -120822,
+    description: 'Configuration source `{sourceName}` returned an invalid source result.'
+  },
+
+  InvalidConfigurationContext: {
+    code: -120823,
+    description: 'The configuration context is invalid. Create contexts with createConfigurationContext().'
+  },
+
+  InvalidConfigurationSourceMode: {
+    code: -120824,
+    description: 'Configuration source `{sourceName}` uses unsupported mode `{mode}`. Use `fallback`, `overrideEnvironment`, or `enforce`.'
+  },
+
+  JsonConfigurationFileReadFailed: {
+    code: -120825,
+    description: 'JSON configuration file `{filePath}` could not be read.'
+  },
+
+  InvalidJsonConfigurationFile: {
+    code: -120826,
+    description: 'JSON configuration file `{filePath}` does not contain valid JSON.'
+  },
+
+  JsonConfigurationDocumentRequired: {
+    code: -120827,
+    description: 'JSON configuration file `{filePath}` must contain an object at the document root.'
+  },
+
   // ============================================================================
   // Application Configuration Errors (-120850 to -120902)
   // ============================================================================

package/src/index.ts

@@ -8,6 +8,7 @@ export { authorizeJWT, buildJwksUri, clearJwksClients } from './auth/jwt-middlew
 
 export * from './app'
 export * from './cards'
+export * from './configuration'
 export * from './connector-client'
 export { Errors as HostingErrors } from './errorHelper'
 export * from './invoke'

package/src/outboundHostValidator.ts

@@ -3,7 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import { parseBooleanEnv } from './utils/env'
+import {
+  ConfigurationContext,
+  getConfigurationSnapshot
+} from './configuration/configuration'
+import { loadModernEnvironmentConfiguration } from './configuration/environmentConfiguration'
+import { mergeDefined } from './utils'
 
 /** Hosts used by Microsoft channel callbacks and hosted attachments. */
 const DEFAULT_MICROSOFT_HOSTS = Object.freeze([
@@ -17,11 +22,11 @@ const DEFAULT_MICROSOFT_HOSTS = Object.freeze([
   'blob.core.windows.net'
 ])
 
-const OUTBOUND_HOST_VALIDATOR_ENV_PREFIX = 'OutboundHostValidator__'
-const OUTBOUND_HOST_VALIDATOR_ENV_PREFIX_UPPER = OUTBOUND_HOST_VALIDATOR_ENV_PREFIX.toUpperCase()
-
 /** Configuration for the shared outbound-host allowlist. */
 export interface OutboundHostValidatorOptions {
+  /** Optional host-scoped external configuration. */
+  configurationContext?: ConfigurationContext
+
   /** Enables allowlist enforcement. Defaults to `false`. */
   enabled?: boolean
 
@@ -56,14 +61,17 @@ export class OutboundHostValidator implements OutboundUrlPolicy {
   private readonly suffixes: ReadonlySet<string>
 
   public constructor (options: OutboundHostValidatorOptions = {}) {
-    this.enabled = options.enabled ?? false
+    const resolved = options.configurationContext
+      ? resolveOutboundHostValidatorOptions(options)
+      : options
+    this.enabled = resolved.enabled ?? false
 
     const suffixes = new Set<string>()
-    if (options.includeDefaultMicrosoftHosts ?? true) {
+    if (resolved.includeDefaultMicrosoftHosts ?? true) {
       for (const host of DEFAULT_MICROSOFT_HOSTS) suffixes.add(host)
     }
 
-    for (const host of options.hosts ?? []) {
+    for (const host of resolved.hosts ?? []) {
       const normalized = normalizeConfiguredHost(host)
       if (normalized) suffixes.add(normalized)
     }
@@ -93,47 +101,32 @@ export class OutboundHostValidator implements OutboundUrlPolicy {
  * indexed values such as `Hosts__0`, `Hosts__1`, and so on.
  */
 export function loadOutboundHostValidatorOptionsFromEnv (): OutboundHostValidatorOptions {
-  const result: OutboundHostValidatorOptions = {}
-  const indexedHosts = new Map<number, string>()
-  const hosts: string[] = []
-
-  for (const [envKey, rawValue] of Object.entries(process.env)) {
-    const upperKey = envKey.toUpperCase()
-    if (!upperKey.startsWith(OUTBOUND_HOST_VALIDATOR_ENV_PREFIX_UPPER)) continue
-
-    const property = envKey.substring(OUTBOUND_HOST_VALIDATOR_ENV_PREFIX.length)
-    const upperProperty = property.toUpperCase()
-
-    if (upperProperty === 'ENABLED') {
-      const value = parseBooleanEnv(rawValue)
-      if (value !== undefined) result.enabled = value
-    } else if (upperProperty === 'INCLUDEDEFAULTMICROSOFTHOSTS') {
-      const value = parseBooleanEnv(rawValue)
-      if (value !== undefined) result.includeDefaultMicrosoftHosts = value
-    } else if (upperProperty === 'HOSTS' && rawValue) {
-      hosts.push(...rawValue.split(',').map(host => host.trim()).filter(Boolean))
-    } else {
-      const match = /^HOSTS__(\d+)$/i.exec(property)
-      if (match && rawValue?.trim()) indexedHosts.set(Number(match[1]), rawValue.trim())
-    }
-  }
-
-  for (const [, host] of [...indexedHosts.entries()].sort(([left], [right]) => left - right)) {
-    hosts.push(host)
-  }
-  if (hosts.length > 0) result.hosts = hosts
+  return { ...loadModernEnvironmentConfiguration().outboundHostValidator }
+}
 
-  return result
+/** Creates a validator using the shared configuration precedence. */
+export function createOutboundHostValidator (options: OutboundHostValidatorOptions = {}): OutboundHostValidator {
+  return new OutboundHostValidator(resolveOutboundHostValidatorOptions(options))
 }
 
-/** Creates the default validator, with explicit settings overriding the environment. */
-export function createOutboundHostValidator (options?: OutboundHostValidatorOptions): OutboundHostValidator {
+function resolveOutboundHostValidatorOptions (
+  options: OutboundHostValidatorOptions
+): OutboundHostValidatorOptions {
+  const external = getConfigurationSnapshot(options.configurationContext)
   const fromEnv = loadOutboundHostValidatorOptionsFromEnv()
-  return new OutboundHostValidator({
-    enabled: options?.enabled ?? fromEnv.enabled,
-    includeDefaultMicrosoftHosts: options?.includeDefaultMicrosoftHosts ?? fromEnv.includeDefaultMicrosoftHosts,
-    hosts: options?.hosts ?? fromEnv.hosts
-  })
+  const direct: OutboundHostValidatorOptions = {}
+  if (options.enabled !== undefined) direct.enabled = options.enabled
+  if (options.includeDefaultMicrosoftHosts !== undefined) {
+    direct.includeDefaultMicrosoftHosts = options.includeDefaultMicrosoftHosts
+  }
+  if (options.hosts !== undefined) direct.hosts = options.hosts
+  return mergeDefined<OutboundHostValidatorOptions>(
+    external.fallback.outboundHostValidator,
+    fromEnv,
+    external.overrideEnvironment.outboundHostValidator,
+    direct,
+    external.enforce.outboundHostValidator
+  )
 }
 
 function getUrlHost (input: string | URL | null | undefined): string | undefined {

package/src/storage/fileStorage.ts

@@ -5,10 +5,13 @@
 
 import path from 'path'
 import fs from 'fs'
-import { Storage, StoreItem } from './storage'
-import { trace } from '@microsoft/agents-telemetry'
+import { Storage, StoreItem, StorageWriteOptions } from './storage'
+import { getStorageWriteExpiry } from './storageExpiry'
+import { debug, redactString, trace } from '@microsoft/agents-telemetry'
 import { StorageTraceDefinitions } from '../observability'
 
+const logger = debug('agents:file-storage')
+
 /**
  * A file-based storage implementation that persists data to the local filesystem.
  *
@@ -53,6 +56,7 @@ import { StorageTraceDefinitions } from '../observability'
 export class FileStorage implements Storage {
   private _folder: string
   private _stateFile: Record<string, string>
+  private _metadataFile: { expirations?: Record<string, number> }
 
   /**
    * Creates a new FileStorage instance that stores data in the specified folder.
@@ -75,8 +79,14 @@ export class FileStorage implements Storage {
     if (!fs.existsSync(path.join(folder, 'state.json'))) {
       fs.writeFileSync(path.join(folder, 'state.json'), '{}')
     }
+    if (!fs.existsSync(path.join(folder, 'state.metadata.json'))) {
+      fs.writeFileSync(path.join(folder, 'state.metadata.json'), '{}')
+    }
     const data = fs.readFileSync(path.join(folder, 'state.json'), 'utf8')
     this._stateFile = JSON.parse(data)
+    const metadata = fs.readFileSync(path.join(folder, 'state.metadata.json'), 'utf8')
+    this._metadataFile = JSON.parse(metadata)
+    this._metadataFile.expirations ??= {}
   }
 
   /**
@@ -100,12 +110,23 @@ export class FileStorage implements Storage {
           reject(new ReferenceError('Keys are required when reading.'))
         } else {
           const data: StoreItem = {}
+          let storageChanged = false
           for (const key of keys) {
+            if (this.isExpired(key)) {
+              logger.info('Item expired, deleting from storage', { key: redactString(key, true) })
+              delete this._stateFile[key]
+              delete this._metadataFile.expirations![key]
+              storageChanged = true
+              continue
+            }
             const item = this._stateFile[key]
             if (item) {
               data[key] = item
             }
           }
+          if (storageChanged) {
+            this.writeFiles()
+          }
           resolve(data)
         }
       })
@@ -128,14 +149,20 @@ export class FileStorage implements Storage {
    * > Any eTag values in the changes object are ignored.
    *
    */
-  write (changes: StoreItem) : Promise<void> {
+  write (changes: StoreItem, options?: StorageWriteOptions) : Promise<void> {
     return trace(StorageTraceDefinitions.write, async ({ record }) => {
+      const expiresAt = getStorageWriteExpiry(options)
       const keys = Object.keys(changes)
       record({ keyCount: keys?.length })
       for (const key of keys) {
         this._stateFile[key] = changes[key]
+        if (expiresAt === undefined) {
+          delete this._metadataFile.expirations![key]
+        } else {
+          this._metadataFile.expirations![key] = expiresAt
+        }
       }
-      fs.writeFileSync(this._folder + '/state.json', JSON.stringify(this._stateFile, null, 2))
+      this.writeFiles()
     })
   }
 
@@ -162,11 +189,22 @@ export class FileStorage implements Storage {
         } else {
           for (const key of keys) {
             delete this._stateFile[key]
+            delete this._metadataFile.expirations![key]
           }
-          fs.writeFileSync(this._folder + '/state.json', JSON.stringify(this._stateFile, null, 2))
+          this.writeFiles()
           resolve(undefined)
         }
       })
     })
   }
+
+  private isExpired (key: string): boolean {
+    const expiresAt = this._metadataFile.expirations?.[key]
+    return expiresAt !== undefined && expiresAt <= Date.now()
+  }
+
+  private writeFiles (): void {
+    fs.writeFileSync(path.join(this._folder, 'state.json'), JSON.stringify(this._stateFile, null, 2))
+    fs.writeFileSync(path.join(this._folder, 'state.metadata.json'), JSON.stringify(this._metadataFile, null, 2))
+  }
 }

package/src/storage/index.ts

@@ -1,3 +1,4 @@
 export * from './storage'
+export * from './storageExpiry'
 export * from './memoryStorage'
 export * from './fileStorage'

package/src/storage/memoryStorage.ts

@@ -3,10 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { trace } from '@microsoft/agents-telemetry'
+import { redactString, trace } from '@microsoft/agents-telemetry'
 import { ExceptionHelper } from '@microsoft/agents-activity'
 import { StorageTraceDefinitions } from '../observability'
-import { Storage, StoreItem } from './storage'
+import { Storage, StoreItem, StorageWriteOptions } from './storage'
+import { getStorageWriteExpiry } from './storageExpiry'
 import { debug } from '@microsoft/agents-telemetry'
 import { Errors } from '../errorHelper'
 
@@ -28,6 +29,7 @@ const logger = debug('agents:memory-storage')
  */
 export class MemoryStorage implements Storage {
   private static instance: MemoryStorage
+  private expirations: { [k: string]: number } = {}
   /**
    * Counter used to generate unique eTags for stored items
    */
@@ -74,6 +76,12 @@ export class MemoryStorage implements Storage {
       const data: StoreItem = {}
       for (const key of keys) {
         logger.debug(`Reading key: ${key}`)
+        if (this.isExpired(key)) {
+          logger.info('Item expired, deleting from memory', { key: redactString(key, true) })
+          delete this.memory[key]
+          delete this.expirations[key]
+          continue
+        }
         const item = this.memory[key]
         if (item) {
           data[key] = JSON.parse(item)
@@ -97,22 +105,29 @@ export class MemoryStorage implements Storage {
    * has the same eTag. If an item has an eTag of '*' or no eTag, it will
    * always be written regardless of the current state.
    */
-  async write (changes: StoreItem): Promise<void> {
+  async write (changes: StoreItem, options?: StorageWriteOptions): Promise<void> {
     return trace(StorageTraceDefinitions.write, async ({ record }) => {
-      if (!changes || changes.length === 0) {
+      const keys = changes ? Object.keys(changes) : []
+      if (!changes || keys.length === 0) {
         throw ExceptionHelper.generateException(ReferenceError, Errors.StorageWriteChangesRequired)
       }
-      record({ keyCount: changes.length })
+      const expiresAt = getStorageWriteExpiry(options)
+      record({ keyCount: keys.length })
 
       for (const [key, newItem] of Object.entries(changes)) {
         logger.debug(`Writing key: ${key}`)
+        if (this.isExpired(key)) {
+          logger.info('Item expired, deleting from memory', { key: redactString(key, true) })
+          delete this.memory[key]
+          delete this.expirations[key]
+        }
         const oldItemStr = this.memory[key]
         if (!oldItemStr || newItem.eTag === '*' || !newItem.eTag) {
-          this.saveItem(key, newItem)
+          this.saveItem(key, newItem, expiresAt)
         } else {
           const oldItem = JSON.parse(oldItemStr)
           if (newItem.eTag === oldItem.eTag) {
-            this.saveItem(key, newItem)
+            this.saveItem(key, newItem, expiresAt)
           } else {
             throw ExceptionHelper.generateException(Error, Errors.StorageETagConflict, undefined, { key })
           }
@@ -133,6 +148,7 @@ export class MemoryStorage implements Storage {
       logger.debug(`Deleting keys: ${keys.join(', ')}`)
       for (const key of keys) {
         delete this.memory[key]
+        delete this.expirations[key]
       }
     })
   }
@@ -151,8 +167,18 @@ export class MemoryStorage implements Storage {
    *
    * @private
    */
-  private saveItem (key: string, item: unknown): void {
+  private saveItem (key: string, item: unknown, expiresAt?: number): void {
     const clone = Object.assign({}, item, { eTag: (this.etag++).toString() })
     this.memory[key] = JSON.stringify(clone)
+    if (expiresAt === undefined) {
+      delete this.expirations[key]
+    } else {
+      this.expirations[key] = expiresAt
+    }
+  }
+
+  private isExpired (key: string): boolean {
+    const expiresAt = this.expirations[key]
+    return expiresAt !== undefined && expiresAt <= Date.now()
   }
 }

package/src/storage/storage.ts

@@ -50,6 +50,20 @@ export interface StoreItems {
   [key: string]: any;
 }
 
+/**
+ * Options for writing items to storage.
+ */
+export interface StorageWriteOptions {
+  /**
+   * Optional time to live, in seconds, for written items.
+   *
+   * @remarks
+   * When set, storage providers should stop returning the written items after
+   * this duration has elapsed. Values must be finite numbers greater than zero.
+   */
+  ttl?: number;
+}
+
 /**
  * A factory function to generate storage keys based on the conversation context.
  *
@@ -91,7 +105,7 @@ export interface Storage {
    * @returns A promise that resolves when the write operation is complete
    * @throws If the changes object is empty or undefined, or if an eTag conflict occurs and optimistic concurrency is enabled
    */
-  write: (changes: StoreItem) => Promise<void>;
+  write: (changes: StoreItem, options?: StorageWriteOptions) => Promise<void>;
 
   /**
    * Deletes store items from storage.

package/src/storage/storageExpiry.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { StorageWriteOptions } from './storage'
+import { ExceptionHelper } from '@microsoft/agents-activity'
+import { Errors } from '../errorHelper'
+
+export function getStorageWriteExpiry (options?: StorageWriteOptions): number | undefined {
+  const ttl = options?.ttl
+  if (ttl === undefined) {
+    return undefined
+  }
+
+  if (!Number.isFinite(ttl) || ttl <= 0) {
+    throw ExceptionHelper.generateException(RangeError, Errors.InvalidStorageTtl)
+  }
+
+  return Date.now() + ttl * 1000
+}

package/src/utils/env.ts

@@ -10,6 +10,69 @@
  * normalize behavior across the package without growing the public API.
  */
 
+export interface LoadEnv {
+  [upperKey: string]: { key: string, value: any }
+}
+
+type ParserSettings<K extends string> = {
+  [key in K]: (value: string) => { key?: string, value?: any } | undefined
+}
+
+/**
+ * Indexes non-empty environment values case-insensitively while preserving
+ * their original key spelling.
+ */
+export function loadEnvSettings (
+  callback: (key: string, value: string) => void,
+  environment: NodeJS.ProcessEnv = process.env
+): LoadEnv {
+  const env: LoadEnv = {}
+  for (const [envKey, envValue] of Object.entries(environment)) {
+    if (!envValue?.trim()) {
+      continue
+    }
+
+    env[envKey.toUpperCase()] = { key: envKey, value: envValue }
+    callback(envKey, envValue)
+  }
+
+  return env
+}
+
+/**
+ * Creates a case-insensitive parser for a fixed set of environment keys.
+ */
+export function envParser<K extends string> (
+  settings: ParserSettings<K> & ThisType<ParserSettings<K>>
+) {
+  const keys = Object.keys(settings) as K[]
+  const upperKeys = keys.reduce((acc, key) => {
+    acc[key.toUpperCase()] = key
+    return acc
+  }, {} as Record<string, K>)
+
+  return {
+    keys,
+    parse (key: K, value: string) {
+      const match = upperKeys[key.toUpperCase()]
+      if (!match) {
+        return {}
+      }
+
+      const result = settings[match](value)
+      return { key: result?.key ?? match, value: result?.value }
+    }
+  }
+}
+
+export const envParserUtils = {
+  bypass: (value: string) => ({ value }),
+  redirect: <Parser extends ReturnType<typeof envParser>>(
+    parser: Parser,
+    key: Parameters<Parser['parse']>[0]
+  ) => (value: string) => parser.parse(key, value)
+}
+
 /**
  * Parses an environment-variable string into a boolean.
  *

package/src/utils.ts

@@ -12,3 +12,13 @@ export const prune = <T extends Record<string, any>>(obj: T) => {
   const entries = Object.entries(obj).filter(([, value]) => value !== undefined)
   return Object.fromEntries(entries) as T
 }
+
+export const mergeDefined = <T extends Record<string, any>>(
+  ...layers: readonly (Partial<T> | undefined)[]
+): T => {
+  const result: Partial<T> = {}
+  for (const layer of layers) {
+    if (layer) Object.assign(result, prune(layer))
+  }
+  return result as T
+}