@microsoft/agents-hosting 1.9.0-beta.8.gf58e66b2ee → 1.9.1

package/src/auth/settings.ts

@@ -11,6 +11,8 @@ import type { SidecarConnectionSettings } from './sidecar/sidecarConnectionSetti
 
 export type { MsalConnectionSettings } from './msal/msalConnectionSettings'
 export type { SidecarConnectionSettings } from './sidecar/sidecarConnectionSettings'
+export { envParser, envParserUtils, loadEnvSettings } from '../utils/env'
+export type { LoadEnv } from '../utils/env'
 
 const logger = debug('agents:authConfiguration')
 
@@ -32,25 +34,6 @@ export const DEFAULT_CONNECTION_MAP: ConnectionMapItem = { serviceUrl: '*', conn
 export type ConnectionKeys = keyof Omit<AuthConfiguration, 'connections' | 'connectionsMap'>
 export type ConnectionMapKeys = keyof ConnectionMapItem
 
-export interface LoadEnv {
-  [upperKey: string]: { key: string, value: any }
-}
-
-export function loadEnvSettings (callback: (key: string, value: string) => void) {
-  const env: LoadEnv = {}
-  for (const [envKey, envValue] of Object.entries(process.env)) {
-    if (!envValue?.trim()) {
-      continue
-    }
-
-    env[envKey.toUpperCase()] = { key: envKey, value: envValue }
-
-    callback(envKey, envValue)
-  }
-
-  return env
-}
-
 export function applyDefaultSettings (config: AuthConfiguration) {
   const settings = { ...config }
   settings.authorityEndpoint ??= settings.authority ?? AUTHORITY_DEFAULT
@@ -91,68 +74,6 @@ export function applyDefaultSettings (config: AuthConfiguration) {
   return settings
 }
 
-/**
- * A type representing a parser settings object.
- */
-type ParserSettings<K extends string> = {
-  [key in K]: (value: string) => { key?: string, value?: any } | undefined
-}
-
-/**
- * Creates an environment variable parser that maps the variable keys to parsing functions.
- * @param settings An object where each key is an environment variable name and the value is a function
- * that takes the variable value as input and returns an object with optional `key` and `value` properties.
- * @remarks
- * The `key` property in the returned object can be used to rename the environment variable key,
- * while the `value` property contains the parsed value.
- * @returns An object with a `parse` method that takes an environment variable key and value,
- * and returns the parsed result.
- */
-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,
-    /**
-     * Parses the given environment variable key and value using the provided settings.
-     * @param key The environment variable key.
-     * @param value The environment variable value.
-     * @returns The parsed result with optional renamed key and parsed value.
-     */
-    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 }
-    }
-  }
-}
-
-/**
- * Utility functions for environment variable parsers.
- */
-export const envParserUtils = {
-  /**
-   * Bypass parser that returns the value as is.
-   * @param value The environment variable value.
-   * @returns An object with the original value.
-   */
-  bypass: (value: string) => ({ value }),
-  /**
-   * Redirects the parsing to another parser for a specific key.
-   * @param parser The target parser to redirect to.
-   * @param key The key to use in the target parser.
-   * @returns A function that takes the environment variable value and returns the parsed result from the target parser.
-   */
-  redirect: <Parser extends ReturnType<typeof envParser>>(parser: Parser, key: Parameters<Parser['parse']>[0]) => (value: string) => parser.parse(key, value)
-}
-
 /**
  * Resolves the full authority URL including the tenant ID.
  * Supports both patterns:
@@ -234,7 +155,9 @@ export interface ConnectionSettingsBase {
    *
    * @remarks
    * Disabled by default for backward compatibility. Tenant-to-issuer binding is always applied
-   * independently when both claims contain comparable tenant GUIDs.
+   * independently when both claims contain comparable tenant GUIDs. Environment configuration
+   * accepts `true`, `false`, `1`, and `0` case-insensitively with surrounding whitespace ignored.
+   * Any other non-empty value fails configuration loading.
    */
   validateIssuer?: boolean
 

package/src/cloudAdapter.ts

@@ -28,12 +28,17 @@ import { HeaderPropagation, HeaderPropagationCollection, HeaderPropagationDefini
 import { JwtPayload } from 'jsonwebtoken'
 import { getTokenServiceEndpoint } from './oauth/customUserTokenAPI'
 import { Connections } from './auth/connections'
-import { parseBooleanEnv, suggestClosest } from './utils/env'
 import { trace } from '@microsoft/agents-telemetry'
 import { AdapterTraceDefinitions } from './observability'
 import { applyAgenticHeaders } from './getProductInfo'
-import { createOutboundHostValidator, OutboundUrlPolicy } from './outboundHostValidator'
+import {
+  createOutboundHostValidator,
+  OutboundUrlPolicy
+} from './outboundHostValidator'
 import { authorizeJWT } from './auth/jwt-middleware'
+import { ConfigurationContext, getConfigurationSnapshot } from './configuration/configuration'
+import { loadModernEnvironmentConfiguration } from './configuration/environmentConfiguration'
+import { mergeDefined } from './utils'
 
 const logger = debug('agents:cloud-adapter')
 
@@ -62,6 +67,11 @@ const logger = debug('agents:cloud-adapter')
  * win over environment variables.
  */
 export interface CloudAdapterOptions {
+  /**
+   * Optional host-scoped external configuration.
+   */
+  configurationContext?: ConfigurationContext
+
   /**
    * When `true`, the default `onTurnError` handler includes `error.stack` in
    * its log output. Defaults to `false`.
@@ -89,123 +99,35 @@ export interface CloudAdapterOptions {
   validateServiceUrl?: boolean
 }
 
-const DEFAULT_CLOUD_ADAPTER_OPTIONS: Required<CloudAdapterOptions> = {
+type ResolvedCloudAdapterOptions = Required<Pick<CloudAdapterOptions, 'emitStackTrace' | 'validateServiceUrl'>>
+
+const DEFAULT_CLOUD_ADAPTER_OPTIONS: ResolvedCloudAdapterOptions = {
   emitStackTrace: false,
   validateServiceUrl: false
 }
 
-/** Env-var prefix for {@link CloudAdapterOptions} (matches .NET config section). */
-const CLOUD_ADAPTER_OPTIONS_ENV_PREFIX = 'CloudAdapterOptions__'
-const CLOUD_ADAPTER_OPTIONS_ENV_PREFIX_UPPER = CLOUD_ADAPTER_OPTIONS_ENV_PREFIX.toUpperCase()
-
-/**
- * Declarative env-var parser for {@link CloudAdapterOptions}.
- *
- * Shape mirrors `envParser<K>` introduced in PR #1119
- * (`packages/agents-hosting/src/auth/settings.ts`) so this loader can be
- * swapped for the shared utility once that lands. Each entry is a
- * `(rawValue) => parsedValue | undefined` function. Lookups are
- * case-insensitive via the `upperKeys` map, matching the upstream
- * convention and accommodating hosts that uppercase env-var names.
- *
- * Adding a new option to `CloudAdapterOptions` only requires adding an
- * entry here.
- */
-const cloudAdapterOptionsParser = (() => {
-  const schema: {
-    [K in keyof Required<CloudAdapterOptions>]: (raw: string | undefined) => CloudAdapterOptions[K]
-  } = {
-    emitStackTrace: parseBooleanEnv,
-    validateServiceUrl: parseBooleanEnv
-  }
-  const keys = Object.keys(schema) as Array<keyof CloudAdapterOptions>
-  const upperKeys = keys.reduce<Record<string, keyof CloudAdapterOptions>>((acc, key) => {
-    acc[key.toUpperCase()] = key
-    return acc
-  }, {})
-  return {
-    schema,
-    keys,
-    /**
-     * Resolves an env-var property name (case-insensitive) to its canonical
-     * `CloudAdapterOptions` key, or `undefined` when the name is unknown.
-     */
-    resolveKey (property: string): keyof CloudAdapterOptions | undefined {
-      return upperKeys[property.toUpperCase()]
-    }
-  }
-})()
-
-/**
- * Per-process dedup set for configuration warnings. Without this, every
- * `new CloudAdapter()` re-scans `process.env` and re-emits warnings for any
- * typo'd `CloudAdapterOptions__*` key (or unparseable value), which spams
- * stderr in multi-adapter scenarios (tests, proactive flows, DI containers).
- */
-const warnedConfigKeys = new Set<string>()
-
-function emitConfigWarning (envKey: string, message: string): void {
-  if (warnedConfigKeys.has(envKey)) return
-  warnedConfigKeys.add(envKey)
-  // Visible by default (writes synchronously to stderr) so users see typos
-  // and bad values without having to opt in via `DEBUG=agents:cloud-adapter:*`.
-  // Hosts that want to route or suppress can intercept `console.warn` or
-  // subscribe to the `agents:cloud-adapter:warn` debug namespace below.
-  console.warn(`[agents:cloud-adapter] ${message}`)
-  logger.warn(message)
-}
-
-/**
- * Scans `process.env` for keys with the `CloudAdapterOptions__` prefix
- * (case-insensitive) and returns the parsed partial options. Unknown keys
- * and values that fail to parse are warned about once per process via
- * `console.warn` (so they are visible by default without enabling debug)
- * and through the `agents:cloud-adapter:warn` debug channel for log
- * aggregators. Hosts that want to route or suppress these diagnostics can
- * intercept `console.warn` or filter the debug namespace.
- */
-function loadCloudAdapterOptionsFromEnv (): CloudAdapterOptions {
-  const result: CloudAdapterOptions = {}
-  for (const [envKey, rawValue] of Object.entries(process.env)) {
-    const upper = envKey.toUpperCase()
-    if (!upper.startsWith(CLOUD_ADAPTER_OPTIONS_ENV_PREFIX_UPPER)) continue
-    const property = envKey.substring(CLOUD_ADAPTER_OPTIONS_ENV_PREFIX.length)
-    const canonical = cloudAdapterOptionsParser.resolveKey(property)
-    if (!canonical) {
-      const suggestion = suggestClosest(property, cloudAdapterOptionsParser.keys as readonly string[], 4)
-      const hint = suggestion ? ` Did you mean "${CLOUD_ADAPTER_OPTIONS_ENV_PREFIX}${suggestion}"?` : ''
-      emitConfigWarning(envKey, `Unknown CloudAdapterOptions env var: ${envKey} (ignored).${hint}`)
-      continue
-    }
-    const parsed = cloudAdapterOptionsParser.schema[canonical](rawValue) as any
-    if (parsed !== undefined) {
-      (result as any)[canonical] = parsed
-    } else if (rawValue !== undefined && rawValue.trim() !== '') {
-      // Known key, recognized but unparseable value (e.g. `yes`, `on`, `enabled`).
-      // For a security-relevant flag like `validateServiceUrl`, silent
-      // fallthrough is the dangerous failure mode — surface it.
-      // Note: parseBooleanEnv treats whitespace-only as unset, so don't warn
-      // on `'   '`; only warn when the user actually typed something.
-      emitConfigWarning(
-        `${envKey}=${rawValue}`,
-        `Ignored ${envKey}=${rawValue}; expected one of true/false/1/0.`
-      )
-    }
-  }
-  return result
-}
-
 /**
  * Resolves a `CloudAdapterOptions` instance from an explicit argument or, if
  * absent, from environment variables. Values supplied in the explicit object
  * win over env vars.
  */
-function resolveCloudAdapterOptions (options?: CloudAdapterOptions): Required<CloudAdapterOptions> {
-  const fromEnv = loadCloudAdapterOptionsFromEnv()
-  return {
-    emitStackTrace: options?.emitStackTrace ?? fromEnv.emitStackTrace ?? DEFAULT_CLOUD_ADAPTER_OPTIONS.emitStackTrace,
-    validateServiceUrl: options?.validateServiceUrl ?? fromEnv.validateServiceUrl ?? DEFAULT_CLOUD_ADAPTER_OPTIONS.validateServiceUrl
-  }
+function resolveCloudAdapterOptions (options?: CloudAdapterOptions): ResolvedCloudAdapterOptions {
+  const external = getConfigurationSnapshot(options?.configurationContext)
+  const fromEnv = loadModernEnvironmentConfiguration(
+    process.env,
+    { reportCloudAdapterDiagnostics: true }
+  ).cloudAdapterOptions
+  return mergeDefined<ResolvedCloudAdapterOptions>(
+    DEFAULT_CLOUD_ADAPTER_OPTIONS,
+    external.fallback.cloudAdapterOptions,
+    fromEnv,
+    external.overrideEnvironment.cloudAdapterOptions,
+    {
+      emitStackTrace: options?.emitStackTrace,
+      validateServiceUrl: options?.validateServiceUrl
+    },
+    external.enforce.cloudAdapterOptions
+  )
 }
 
 /**
@@ -251,7 +173,7 @@ export class CloudAdapter extends BaseAdapter {
    */
   connectionManager: Connections
 
-  private readonly _options: Required<CloudAdapterOptions>
+  private readonly _options: ResolvedCloudAdapterOptions
   private readonly _hostValidator: OutboundUrlPolicy
 
   /**
@@ -266,11 +188,14 @@ export class CloudAdapter extends BaseAdapter {
    */
   constructor (authConfig?: AuthConfiguration, authProvider?: AuthProvider, userTokenClient?: UserTokenClient, options?: CloudAdapterOptions, outboundHostValidator?: OutboundUrlPolicy) {
     super()
-    this.authConfig = authConfig = getAuthConfigWithDefaults(authConfig)
+    this.authConfig = authConfig = getAuthConfigWithDefaults(authConfig, {
+      configurationContext: options?.configurationContext
+    })
     this.jwtMiddleware = authorizeJWT(authConfig)
     this.connectionManager = new MsalConnectionManager(undefined, undefined, authConfig)
     this._options = resolveCloudAdapterOptions(options)
-    this._hostValidator = outboundHostValidator ?? createOutboundHostValidator()
+    this._hostValidator = outboundHostValidator ??
+      createOutboundHostValidator({ configurationContext: options?.configurationContext })
 
     // Install a CloudAdapter-aware default `onTurnError` that honors
     // `emitStackTrace`. The base class default only logs the message; we

package/src/configuration/botFrameworkEnvironmentCompatibility.ts

@@ -0,0 +1,245 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+  ConfigurationLayer,
+  createConfigurationLayer,
+  freezeConfigurationLayer,
+  isConfigurationInputError,
+  isInvalidConfigurationValueError,
+  setConfigurationValue
+} from './configuration'
+import { LoadEnv, loadEnvSettings } from '../utils/env'
+
+const DEFAULT_CONNECTION_ID = 'serviceConnection'
+
+const flatConnectionProperties = {
+  MicrosoftAppTenantId: 'tenantId',
+  MicrosoftAppId: 'clientId',
+  MicrosoftAppPassword: 'clientSecret',
+  certPemFile: 'certPemFile',
+  certKeyFile: 'certKeyFile',
+  connectionName: 'connectionName',
+  MicrosoftAppClientId: 'federatedClientId',
+  authorityEndpoint: 'authorityEndpoint',
+  scope: 'scopes',
+  altBlueprintConnectionName: 'altBlueprintConnectionName',
+  alternateBlueprintConnectionName: 'altBlueprintConnectionName',
+  WIDAssertionFile: 'WIDAssertionFile',
+  azureRegion: 'azureRegion',
+  sendX5C: 'sendX5C',
+  msalRetryCount: 'msalRetryCount',
+  authType: 'authType',
+  federatedTokenFile: 'federatedTokenFile',
+  idpmResource: 'idpmResource',
+  sidecarBaseUrl: 'sidecarBaseUrl',
+  serviceName: 'serviceName',
+  blueprintServiceName: 'blueprintServiceName',
+  bypassLocalNetworkRestriction: 'bypassLocalNetworkRestriction',
+  requestTimeout: 'requestTimeout',
+  retryCount: 'retryCount',
+  validateIssuer: 'validateIssuer'
+} as const
+
+const prefixedConnectionProperties = {
+  tenantId: 'tenantId',
+  clientId: 'clientId',
+  clientSecret: 'clientSecret',
+  certPemFile: 'certPemFile',
+  certKeyFile: 'certKeyFile',
+  connectionName: 'connectionName',
+  FICClientId: 'federatedClientId',
+  authorityEndpoint: 'authorityEndpoint',
+  scope: 'scopes',
+  altBlueprintConnectionName: 'altBlueprintConnectionName',
+  alternateBlueprintConnectionName: 'altBlueprintConnectionName',
+  WIDAssertionFile: 'WIDAssertionFile',
+  azureRegion: 'azureRegion',
+  sendX5C: 'sendX5C',
+  msalRetryCount: 'msalRetryCount',
+  authType: 'authType',
+  federatedTokenFile: 'federatedTokenFile',
+  idpmResource: 'idpmResource',
+  sidecarBaseUrl: 'sidecarBaseUrl',
+  serviceName: 'serviceName',
+  blueprintServiceName: 'blueprintServiceName',
+  bypassLocalNetworkRestriction: 'bypassLocalNetworkRestriction',
+  requestTimeout: 'requestTimeout',
+  retryCount: 'retryCount',
+  validateIssuer: 'validateIssuer'
+} as const
+
+const legacyAuthorizationProperties = {
+  type: 'type',
+  connectionName: 'azureBotOAuthConnectionName',
+  connectionTitle: 'title',
+  connectionText: 'text',
+  maxAttempts: 'invalidSignInRetryMax',
+  messages_invalidCode: 'invalidSignInRetryMessage',
+  messages_invalidCodeFormat: 'invalidSignInRetryMessageFormat',
+  messages_maxAttemptsExceeded: 'invalidSignInRetryMaxExceededMessage',
+  obo_connection: 'oboConnectionName',
+  obo_scopes: 'oboScopes',
+  enableSso: 'enableSso',
+  scopes: 'scopes',
+  altBlueprintConnectionName: 'altBlueprintConnectionName'
+} as const
+
+interface BotFrameworkAuthorizationCompatibility {
+  readonly layer: ConfigurationLayer
+  readonly replacements: readonly Readonly<{
+    legacyKey: string
+    modernKey: string
+  }>[]
+}
+
+/** Binds the flat Bot Framework single-connection environment variables. */
+export function loadBotFrameworkEnvironmentConfiguration (
+  env: NodeJS.ProcessEnv = process.env
+): ConfigurationLayer {
+  return bindConnectionCompatibility(env, undefined, flatConnectionProperties)
+}
+
+/** Binds the Bot Framework `<connectionName>_<property>` environment form. */
+export function loadBotFrameworkPrefixedEnvironmentConfiguration (
+  connectionName: string,
+  env: NodeJS.ProcessEnv = process.env
+): ConfigurationLayer {
+  return bindConnectionCompatibility(env, connectionName, prefixedConnectionProperties)
+}
+
+/**
+ * Binds Bot Framework-era `<handlerId>_<property>` authorization variables.
+ * Only known runtime/external handler IDs participate, matching existing
+ * compatibility behavior.
+ */
+export function loadBotFrameworkAuthorizationEnvironmentConfiguration (
+  handlerIds: readonly string[],
+  env: NodeJS.ProcessEnv = process.env
+): BotFrameworkAuthorizationCompatibility {
+  const layer = createConfigurationLayer()
+  const replacements: Array<{ legacyKey: string, modernKey: string }> = []
+  const longestHandlerIdsFirst = [...handlerIds].sort((left, right) => right.length - left.length)
+
+  for (const [legacyKey, rawValue] of Object.entries(env)) {
+    if (!rawValue?.trim()) {
+      continue
+    }
+    const id = longestHandlerIdsFirst.find(candidate =>
+      legacyKey.toLowerCase().startsWith(`${candidate.toLowerCase()}_`)
+    )
+    if (!id) {
+      continue
+    }
+
+    const legacyProperty = legacyKey.substring(id.length + 1)
+    const property = findProperty(legacyAuthorizationProperties, legacyProperty)
+    if (!property) {
+      continue
+    }
+
+    const value = normalizeAuthorizationValue(property, rawValue)
+    if (!trySet(
+      layer,
+      `agentApplication.userAuthorization.handlers.${id}.settings.${property}`,
+      value,
+      legacyKey
+    )) {
+      continue
+    }
+
+    replacements.push({
+      legacyKey,
+      modernKey: `AgentApplication__UserAuthorization__Handlers__${id}__Settings__${property}`
+    })
+  }
+
+  return {
+    layer: freezeConfigurationLayer(layer),
+    replacements: Object.freeze(replacements.map(replacement => Object.freeze(replacement)))
+  }
+}
+
+function bindConnectionCompatibility (
+  env: NodeJS.ProcessEnv,
+  connectionName: string | undefined,
+  properties: Readonly<Record<string, string>>
+): ConfigurationLayer {
+  const layer = createConfigurationLayer()
+  const id = connectionName || DEFAULT_CONNECTION_ID
+  const indexedEnvironment = loadEnvSettings(() => {}, env)
+
+  for (const [legacyProperty, property] of Object.entries(properties)) {
+    const key = connectionName ? `${connectionName}_${legacyProperty}` : legacyProperty
+    const value = findEnvironmentValue(indexedEnvironment, key)
+    if (!value?.trim()) {
+      continue
+    }
+    trySet(
+      layer,
+      `connections.${id}.settings.${property}`,
+      normalizeConnectionValue(property, value),
+      key,
+      property === 'validateIssuer'
+    )
+  }
+
+  return freezeConfigurationLayer(layer)
+}
+
+function findEnvironmentValue (env: LoadEnv, key: string): string | undefined {
+  return env[key.toUpperCase()]?.value
+}
+
+function findProperty (
+  properties: Readonly<Record<string, string>>,
+  input: string
+): string | undefined {
+  const key = Object.keys(properties).find(candidate => candidate.toLowerCase() === input.toLowerCase())
+  return key ? properties[key] : undefined
+}
+
+function normalizeConnectionValue (property: string, value: string): string {
+  if (property === 'sendX5C' || property === 'bypassLocalNetworkRestriction') {
+    return String(value === 'true')
+  }
+  if (property === 'msalRetryCount' || property === 'requestTimeout' || property === 'retryCount') {
+    const parsed = Number.parseInt(value, 10)
+    return Number.isFinite(parsed) ? String(parsed) : value
+  }
+  return value
+}
+
+function normalizeAuthorizationValue (property: string, value: string): string {
+  if (property === 'enableSso') {
+    return String(value !== 'false')
+  }
+  if (property === 'invalidSignInRetryMax') {
+    const parsed = Number.parseInt(value)
+    return Number.isFinite(parsed) ? String(parsed) : value
+  }
+  return value
+}
+
+function trySet (
+  layer: ConfigurationLayer,
+  path: string,
+  value: string,
+  sourceName: string,
+  throwOnInvalidValue = false
+): boolean {
+  try {
+    setConfigurationValue(layer, path, value, sourceName, 'environment')
+    return true
+  } catch (error) {
+    if (!isConfigurationInputError(error)) {
+      throw error
+    }
+    if (throwOnInvalidValue && isInvalidConfigurationValueError(error)) {
+      throw error
+    }
+    return false
+  }
+}